Banking API response codes

Every Banking API error arrives in the standard envelope, with success: false, the HTTP status in http_status_code and a response_code from the catalog. Branch on response_code.

How to react per family#

Request 4xx. The body or parameters are invalid, or the resource does not exist. Fix the call before resending it: retrying as-is returns the same error. This covers INVALID_REQUEST, VALIDATION_ERROR, NOT_FOUND and business codes such as INSUFFICIENT_FUNDS or LIMIT_EXCEEDED.

401 and 403. The token is absent, expired, or its context does not authorize the resource. Renew the access token with the token exchange; if it persists with a fresh token, that context has no permission over the resource.

409 IDEMPOTENCY_CONFLICT. You reused an Idempotency-Key with a different body. Use a new key for the new intent; see safe retries.

429. You exceeded the call limit. Space out requests and retry with backoff.

5xx. Service-side failure. Retry with backoff, and on POST calls resend the same Idempotency-Key so the record is not duplicated. Keep the correlation_id before escalating to support.

Full catalog#

These are the 28 ResponseCode values our API returns, with the HTTP statuses they appear under. OK is the code of successful responses.

A response_code outside this list is not part of the API's 1.0.0 contract: treat it as a generic error based on its HTTP status and report it with the correlation_id.