Errors

The unified error envelope and error codes.

This documentation covers API V1.

Error envelope

Failures always return a JSON envelope with an error object containing a machine-readable code, a human-readable message and the request_id.

json

{
  "error": {
    "code": "INVALID_IBAN",
    "message": "The IBAN format is invalid",
    "request_id": "req_5e6f7a8b"
  }
}

Error codes

Code	HTTP	Description
INVALID_IBAN	422	The IBAN failed format, checksum or structure validation.
INVALID_SWIFT	422	The code is not a valid 8 or 11 character BIC.
INVALID_ROUTING	422	The routing number failed checksum validation.
NOT_FOUND	404	The identifier does not exist in the dataset.
UNAUTHORIZED	401	Missing or invalid API key.
RATE_LIMITED	429	Rate limit exceeded — retry after the indicated delay.
QUOTA_EXCEEDED	402	Monthly request quota exhausted.
INTERNAL	500	Unexpected server error — retry with backoff.

Retries

Retry 429 and 5xx responses with exponential backoff. The Retry-After header indicates the earliest time the next request will be accepted. Never retry 4xx validation errors with the same payload.