# Banking API response codes

> Full response_code catalog for Tilopay's Banking API and how to react to each family.

- kind: concept
- status: stable
- api_version: 1.0.0
- last_verified: 2026-10-22
- url: https://tilopay.com/en/developers/api-bancario/errores

Every Banking API error arrives in the
[standard envelope](/en/developers/api-bancario/convenciones#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 [#familias]

**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`, `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 by repeating
[login and exchange](/en/developers/api-bancario/autenticacion#login); 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](/en/developers/api-bancario/convenciones#reintentos).

**`429 TOO_MANY_REQUESTS`.** Currently applies to authentication and account validation. Space out requests and retry with exponential 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 [#catalogo]

These are the `ResponseCode` values our API returns, with their HTTP statuses. `OK`, `CREATED` and `ACCEPTED` identify successful responses; asynchronous statement requests use `202 ACCEPTED`.

| response_code | HTTP status returned |
|---|---|
| `OK` | — |
| `CREATED` | — |
| `ACCEPTED` | 202 |
| `UNAUTHORIZED` | 401 |
| `FORBIDDEN` | 403 |
| `TOO_MANY_REQUESTS` | 429 |
| `SERVICE_UNAVAILABLE` | 503 |
| `INTERNAL_ERROR` | 500 |
| `INVALID_REQUEST` | 400 |
| `ACCOUNT_ACCESS_DENIED` | 403 |
| `PROVIDER_ERROR` | 502 |
| `INVALID_CREDENTIALS` | 401 |
| `NOT_FOUND` | 404 |
| `ACCOUNT_NOT_FOUND` | 404 |
| `ACCOUNT_NOT_CONFIGURED` | 422 |
| `UNPROCESSABLE_ENTITY` | 422 |
| `PAYMENT_NOT_FOUND` | 404 |
| `INVALID_ACCOUNT_TYPE` | 400 |
| `INVALID_ACCOUNT_FORMAT` | 400 |
| `INVALID_PAYMENT_METHOD` | 400 |
| `PAYMENT_INVALID_PAYLOAD` | 400 |
| `ACCOUNT_INVALID` | 400 |
| `ACCOUNT_HOLDER_MISMATCH` | 400 |
| `IDEMPOTENCY_CONFLICT` | 409 |
| `PAYMENT_DUPLICATE` | 409 |
| `CONFLICT` | 409 |
| `INSUFFICIENT_FUNDS` | 422 |
| `LIMIT_EXCEEDED` | 422 |

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`.