Códigos de error

• Códigos de error
  • Cómo leer un error
  • Códigos HTTP
  • Errores de validación
  • Conflictos de idempotencia
  • Rechazos de la red
  • Reserva de cupo
  • Anulación y reversión
  • Errores de transporte y cifrado
  • Catálogo en vivo
  • Qué mostrarle a tu cliente

Cómo leer un error

Hay tres capas distintas y conviene no confundirlas:

Un pago rechazado no es un error de tu integración: la petición fue correcta y el resultado fue «no». Devuelve 200 u 422 según el caso, y siempre trae el estado de la transacción para que sepas en qué quedó.

{warning} Nunca reintentes automáticamente un rechazo. Si la razón fue fondos insuficientes o una tarjeta bloqueada, reintentar da el mismo resultado y algunos emisores penalizan los reintentos.

Códigos HTTP

Errores de validación

Siempre tienen la misma forma: un message con el primer error y un objeto errors con todos, indexados por el nombre del campo.

{danger} Validación code: 422

{
"message": "El campo payment_card.cvv es obligatorio.",
"errors": {
"payment_card.cvv": ["El campo payment_card.cvv es obligatorio."],
"customer_payer.email": ["El campo customer_payer.email debe ser un correo válido."]
}
}

Las claves de errors usan notación de punto para los campos anidados. Úsalas para marcar el campo exacto en tu formulario en lugar de mostrar un mensaje genérico.

{warning} Una excepción: generar un pago devuelve solo el mapa de errores, sin message ni la envoltura errors:

{
    "payment.amount": ["The payment.amount field is required."]
}

Y si en esa misma llamada omites payment.currency_type, la validación se detiene ahí: recibirás ese único error y ninguno más, porque los límites de monto dependen de la moneda.

Conflictos de idempotencia

Las escrituras de suscripciones aceptan el header Idempotency-Key. Cuando esa clave choca, el cuerpo no tiene la forma de un error de validación: trae un objeto error con su propio type.

{danger} Misma clave, parámetros distintos code: 409

{
"error": {
"type": "idempotency_error",
"message": "La Idempotency-Key ya fue usada con parámetros distintos."
}
}

{danger} Misma clave, misma petición todavía en curso code: 409

{
"error": {
"type": "idempotency_error",
"message": "Una solicitud con esta Idempotency-Key aún está en proceso."
}
}

Cuando en cambio repites exactamente la misma llamada con la misma clave, te devolvemos la respuesta original con el header Idempotency-Replayed: true y sin volver a ejecutar el cobro.

{success} Úsala en todo cobro. El caso que evita: cobras, tu proceso se cae antes de guardar la respuesta, y al reintentar no sabes si el primer intento llegó. Con la misma Idempotency-Key el segundo intento te devuelve la respuesta original en vez de cobrar dos veces.

{info} La clave la eliges tú: una distinta por operación, no por reintento. Un UUID generado al empezar el cobro y reutilizado en todos los reintentos de esa misma operación es lo habitual.

Rechazos de la red

Los más frecuentes. El código llega en response_code de la transacción y, cuando no fue aprobada, también en error.code con su message, su retryable y su action.

{
    "status": "Rechazada",
    "status_key": "rejected",
    "response_code": "51",
    "error": { "code": "51", "message": "…", "retryable": false, "action": "contact_issuer" }
}

{info} El catálogo completo, con todos los códigos y su retryable, se consulta en vivo en GET /api/v1/resources/mit/response-codes. Léelo de ahí en vez de copiar esta tabla: se mantiene sola.

Qué es seguro reintentar

{danger} La diferencia entre «falló» y «no sé si falló» es la que produce cobros dobles. Ante T01 o un 202, consulta con estado de transacción antes de reenviar nada.

Reserva de cupo

Estos son propios de las reservas de cupo.

Anulación y reversión

Errores de transporte y cifrado

{danger} T01 y MIT_INDETERMINATE son los dos casos en que reintentar es peligroso: si la operación sí se aplicó, un reintento la duplica. Consulta el estado o espera el webhook.

Catálogo en vivo

En lugar de copiar esta tabla a tu código, consúltala:

GET /api/v1/resources/mit/response-codes

Cada entrada trae:

Qué mostrarle a tu cliente

Tenemos dos mensajes para cada código y sirven para cosas distintas:

En la respuesta de una transacción, authorization_message_customer y description traen el mensaje que se le puede mostrar al cliente tal cual.

{warning} No le muestres al cliente el código crudo ni el mensaje interno. Un M12 en pantalla no le dice nada a nadie, y los mensajes internos pueden mencionar tu configuración.