Errors

When a request fails, the API returns a JSON object with as much descriptive information as possible. Every error response carries a request_id — include it when contacting support.

string

Error type identifier in snake_case, e.g. resource_not_found, insufficient_funds.

string

Machine-readable error code, e.g. RESOURCE_NOT_FOUND. Use this for programmatic handling.

string

Human-readable description of what went wrong.

object | null

Additional structured context, when available.

string | null

Identifier of the request, for tracing and support.

Example — error response

{
  "error": {
    "type": "resource_not_found",
    "code": "RESOURCE_NOT_FOUND",
    "message": "Beneficiary not found",
    "details": {
      "beneficiary_id": "bene_j7jd54mlirldky8rb93d99qd"
    }
  },
  "request_id": "req_abc123def456"
}

Validation errors

When a request body fails validation, the response is 422 and includes a validation_errors array listing every failed field — not just the first one.

string

The field that failed validation.

string

Why the value was rejected.

any

The invalid value that was provided.

Example — validation error (422)

{
  "error": {
    "type": "validation_error",
    "code": "VALIDATION_ERROR",
    "message": "Amount must be greater than 0; Invalid currency code"
  },
  "validation_errors": [
    { "field": "amount", "message": "Amount must be greater than 0", "value": -100 },
    { "field": "currency", "message": "Invalid currency code", "value": "XXX" }
  ],
  "request_id": "req_abc123def456"
}

HTTP status codes

Status	Meaning
`200`	Request succeeded.
`401`	Missing or invalid signature, stale timestamp, replayed nonce, or unknown API key.
`403`	The API key is not enabled for this API, the request is otherwise not authorized, or a known top-level customer/account belongs to another organization.
`404`	The resource does not exist, or a child resource does not belong to the authorized parent resource in the path.
`422`	The request was understood but failed validation or a business rule.
`429`	Rate limit exceeded. Retry with backoff.

Getting Started

Integration Flows

Webhooks

Endpoints

Validation errors

HTTP status codes

​Validation errors

​HTTP status codes

Validation errors

HTTP status codes