Manejo de errores

Todos los errores de la Facade API tienen la misma forma, sin importar el recurso o el endpoint. Esto hace que tu integración sea predecible: parseas la respuesta de error una sola vez y la reutilizas en toda la API.

Estructura uniforme

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Validation failed: amount must be a positive amount in pesos (e.g. 1500.50).",
    "details": [
      { "field": "amount", "issue": "amount must be a positive amount in pesos (e.g. 1500.50)." }
    ]
  },
  "requestId": "req_3f8a1c9e2b"
}

string

Código estable y legible por máquina. Úsalo para ramificar tu lógica de manejo de errores (no parsees el message).

string

Mensaje legible para personas. Puede cambiar con el tiempo: no lo uses para tomar decisiones en tu código.

array

Presente en errores de validación. Lista de { field, issue } que indica qué campo falló y por qué.

string

Identificador único de la petición. Compártelo con soporte para rastrear exactamente qué pasó.

Catálogo de códigos

HTTP	Código	Cuándo ocurre
`400`	`INVALID_REQUEST`	El payload no pasó la validación: campo faltante o inválido, `autopay` junto con `paymentMethods`, fecha mal formada, etc.
`401`	`AUTHENTICATION_FAILED`	El Token TAPI falta, es inválido o está vencido. Ver Autenticación.
`404`	`RESOURCE_NOT_FOUND`	El recurso referenciado (deuda, producto, contacto, ruta) no existe.
`409`	`RESOURCE_CONFLICT`	La llave externa ya existe: `Idempotency-Key`/`externalRequestId` repetido, `externalSubscriptionId` o `externalPaymentLinkId` duplicado. Ver Idempotencia.
`422`	`RESOLUTION_ERROR`	TapiPay no pudo resolver tu configuración interna (organización o modalidades). Es un problema de configuración del lado del sistema, no de tu request.
`422`	`BUSINESS_RULE_VIOLATION`	La acción no está permitida por el estado del recurso o una regla de negocio: actualizar una deuda que no está en `PENDING`, cancelar una deuda ya pagada, pagar una liga expirada, etc.
`429`	`RATE_LIMITED`	Demasiadas peticiones en poco tiempo. Reintenta con backoff.
`500`	`INTERNAL_ERROR`	Falla inesperada del servidor. No imputable a tu request.
`502`	`SQS_PUBLISH_ERROR`	Falla temporal al encolar el procesamiento interno de un cobro. Reintenta con tu `Idempotency-Key` para no duplicar.

RESOLUTION_ERROR indica que la organización asociada a tu token no está bien configurada en el sistema (por ejemplo, le faltan modalidades activas). Si lo ves de forma persistente, contacta a soporte con el requestId.

El 401 puede llegar en dos formas. Si la falla ocurre en el API Gateway (falta la x-api-key o el token, o son inválidos), la respuesta es {"message":"Unauthorized"}, sin el objeto error. Si la petición pasa el gateway pero la Facade rechaza la autenticación, usa la forma estándar con error.code: AUTHENTICATION_FAILED.

Recomendaciones

Rama por code

Decide tu lógica con error.code, nunca con el texto de message.

Guarda el requestId

Registra el requestId en tus logs: es la forma más rápida de que soporte rastree una petición.

Reintenta con idempotencia

Ante 429, 500 o 502, reintenta con la misma Idempotency-Key para evitar duplicados.

Valida antes de enviar

Usa error.details para mostrar a tus usuarios qué campo corregir en errores 400.

Empieza aquí

Conceptos

Recursos

Portal de pagos

Webhooks

Manejo de errores

Estructura uniforme

Catálogo de códigos

Recomendaciones

Rama por code

Guarda el requestId

Reintenta con idempotencia

Valida antes de enviar

​Estructura uniforme

​Catálogo de códigos

​Recomendaciones

Rama por code

Guarda el requestId

Reintenta con idempotencia

Valida antes de enviar

Estructura uniforme

Catálogo de códigos

Recomendaciones