# Códigos de respuesta del API Bancario

> Catálogo completo de response_code del API Bancario de Tilopay y cómo reaccionar a cada familia.

- kind: concept
- status: stable
- api_version: 1.0.0
- last_verified: 2026-09-02
- url: https://www.tilopay.com/developers/api-bancario/errores

Todo error del API Bancario llega en el
[envelope estándar](/developers/api-bancario/convenciones#envelope), con `success: false`,
el status HTTP en `http_status_code` y un `response_code` del catálogo. Ramificá por
`response_code`.

## Cómo reaccionar por familia [#familias]

**`4xx` de request.** El cuerpo o los parámetros no son válidos, o el recurso no existe.
Corregí la llamada antes de reenviarla: reintentar igual devuelve el mismo error. Acá caen
`INVALID_REQUEST`, `VALIDATION_ERROR`, `NOT_FOUND` y los códigos de negocio como
`INSUFFICIENT_FUNDS` o `LIMIT_EXCEEDED`.

**`401` y `403`.** El token no viaja, venció o su contexto no autoriza el recurso. Renová el
access token con el
[intercambio de token](/developers/api-bancario/autenticacion#exchange); si persiste con
un token nuevo, el contexto no tiene permiso sobre ese recurso.

**`409 IDEMPOTENCY_CONFLICT`.** Reusaste una `Idempotency-Key` con un cuerpo distinto. Usá
una llave nueva para la nueva intención; ver
[reintentos seguros](/developers/api-bancario/convenciones#reintentos).

**`429`.** Superaste el límite de llamadas. Espaciá los envíos y reintentá con backoff.

**`5xx`.** Falla del lado del servicio. Reintentá con backoff, y en los `POST` reenviá la
**misma** `Idempotency-Key` para no duplicar el registro. Guardá el `correlation_id`
antes de escalar a soporte.

## Catálogo completo [#catalogo]

Estos son los 28 valores que el spec declara en el enum `ResponseCode`, con los status
HTTP en los que aparecen. `OK` es el código de las respuestas exitosas.

| response_code | Status HTTP en que el spec lo declara |
|---|---|
| `OK` | 200 |
| `CREATED` | 201 |
| `NO_CONTENT` | — |
| `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 |

Un `response_code` que no esté en esta lista no forma parte del contrato de la versión
1.0.0 del API: tratalo como error genérico según su status HTTP y reportalo con el
`correlation_id`.