Manejo de errores

Todos los errores de la 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é. En el modo lote de POST /v2/debts cada entrada trae además index y externalRequestId del item que falló. Un JSON malformado devuelve [{ "field": "body", "issue": "Invalid JSON syntax" }].

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
`207`	`PARTIAL_UPDATE`	Solo en `PATCH /subscriptions/{id}`: la suscripción se actualizó, pero falló la actualización de alguna de sus deudas ya generadas. El `message` indica cuántas. Ver Suscripciones.
`400`	`INVALID_REQUEST`	El payload o los filtros no pasaron la validación: campo faltante, inválido o no permitido, tipo incorrecto (por ejemplo `"true"` en un booleano), `autopay` junto con `paymentMethods`, fecha mal formada, JSON malformado, etc.
`400`	`BAD_REQUEST`	Tu cliente tiene varias companies y no enviaste `companyCode`. Ver Convenciones de la API.
`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, `externalProductId` o nombre de producto ya en uso. Ver Idempotencia.
`422`	`RESOLUTION_ERROR`	TapiPay no pudo resolver tu configuración: el `companyCode` enviado no es una company de tu cliente, o la organización no está bien configurada (por ejemplo, le faltan modalidades activas).
`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 dos veces una deuda, modificar una suscripción `CANCELLED` o `ENDED`, un `externalClientId` que no corresponde a un contacto, etc.
`429`	`RATE_LIMITED`	Demasiadas peticiones en poco tiempo. Reintenta con backoff.
`500`	`INTERNAL_ERROR`	Falla inesperada del servidor. No imputable a tu request.

RESOLUTION_ERROR sin companyCode indica que la organización asociada a tu token no está bien configurada en el sistema. Si lo ves de forma persistente, contacta a soporte con el requestId.

Errores del API Gateway (`401` y `403`)

Los 401 y 403 los emite el API Gateway, antes de que la petición llegue a la API, y no usan la estructura uniforme: no traen el objeto error ni requestId.

HTTP	Cuándo ocurre	Body
`401`	Falta el token en `x-authorization-token`, es inválido o está vencido.	`{"message": "Unauthorized"}`
`403`	Falta la `x-api-key` o es inválida.	`{"message": "Forbidden"}`
`403`	El token es válido pero no tiene permiso sobre el recurso.	`{"Message": "User is not authorized to access this resource with an explicit deny"}`

En el 403 por falta de permiso el campo viene con mayúscula (Message). Si tu código lee el error, contempla las dos formas: el envelope error de la API y el objeto simple del gateway. Más detalle en Autenticación.

El `message` es informativo

El texto de error.message sirve para depurar, pero no es un contrato: puede cambiar sin aviso. Para decidir qué hacer usa error.code y, en errores de validación, error.details[].field. Los ejemplos de mensajes en estas guías son ilustrativos.

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 o 500, 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í

Novedades

Conceptos

Recursos

Portal de pagos

Webhooks

Manejo de errores

Estructura uniforme

Catálogo de códigos

Errores del API Gateway (`401` y `403`)

El `message` es informativo

Recomendaciones

Rama por code

Guarda el requestId

Reintenta con idempotencia

Valida antes de enviar

​Estructura uniforme

​Catálogo de códigos

​Errores del API Gateway (401 y 403)

​El message es informativo

​Recomendaciones

Rama por code

Guarda el requestId

Reintenta con idempotencia

Valida antes de enviar

Estructura uniforme

Catálogo de códigos

Errores del API Gateway (`401` y `403`)

El `message` es informativo

Recomendaciones