Catálogo de errores

Todo error trae un code estable junto al message para humanos. Las respuestas exitosas no traen code.

Ramificá por code, nunca por message. El code no cambia con Accept-Language; todos los mensajes menos el del 404 de ruteo sí.

El message de un 422 contiene el primer error, con el sufijo (and N more errors) cuando hay varios; errors los agrupa por campo.

Trampa en un 422 con varios errores: el code nombra uno de los campos que fallaron, y no necesariamente el que cita message. POST /payments con el cuerpo vacío contesta message sobre amount y code: "external_reference_required", con los tres campos en errors. Usá code para fallas de un solo campo y para las familias 401/404/405; en un 422 de varios campos, recorré las llaves de errors, que son estables y completas.

Cambió el 2026-08-21. Las versiones anteriores de esta guía afirmaban que esta API no tenía códigos de error legibles por máquina, y por eso los clientes de ejemplo clasificaban los errores comparando texto. Ahora existen, en todos los errores, y los ejemplos ya usan code. Si copiaste un ejemplo viejo, esa es la línea a cambiar: comparar texto ya no es solo frágil - para el error del id numérico es directamente incorrecto (12.3).

15.0 Cuando rechazan una tarjeta: qué código leer y qué reintentar

Un cobro rechazado vuelve como card_declined a nivel de Connect. Eso no dice por qué, y el por qué es lo que decide el siguiente paso. La razón está en IsoResponseCode (y a veces en Errors), y ese es el campo por el que hay que ramificar.

Connect no reintenta un pago rechazado por vos, y no hay una bandera retryable. Decidir si invitar al cliente a intentar de nuevo es trabajo de tu checkout. No confundir esto con los reintentos de webhook de la §14: aquellos reenvían una notificación, nunca reintentan un cobro.

Los cuatro grupos que importan en la práctica:

Esa última fila es la que hay que acertar. No son "probá más tarde": son el emisor diciendo que hay algo mal con la tarjeta misma, y repetir el intento es una señal en la cuenta del comercio, no una oportunidad de venta.

Los códigos comunes, después de un intento de cobro:

Este es el juego ISO 8583. El procesador publica más, menos frecuentes (06–11, 15–29, 31–32, 35–40, 52–53, 60, 62–68, 75–90, 92–95, N0, N3, N4, varios códigos P, XA / XD). Tratá un código que no reconozcas como "no reintentar" y registralo, en vez de adivinar a qué grupo pertenece.

Códigos del paso de 3-D Secure, que ocurren antes o alrededor del cobro y no son aprobaciones:

Fuente: el equipo del API, 25/08/2026, transmitiendo la referencia del procesador. La §16.2 lista las tarjetas de sandbox que producen varios de estos a demanda.

15.1 Mensajes 422 comunes