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, 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 repitiendo login e intercambio; 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 TOO_MANY_REQUESTS. Hoy aplica en autenticación y validación de cuentas. Espaciá los envíos y reintentá con espera exponencial.

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 valores de ResponseCode que retorna nuestro API, con los status HTTP en los que aparecen. OK, CREATED y ACCEPTED identifican respuestas exitosas; la solicitud asíncrona de estados de cuenta usa 202 ACCEPTED.

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.