Códigos de respuesta del API Bancario

Todo error del API Bancario llega en el envelope estándar, 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#

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

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#

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.

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.