Códigos de error

Códigos HTTP

Código	Significado
200	Éxito (GET, PATCH, batch)
201	Transacción creada (POST individual)
204	Transacción eliminada (DELETE)
401	Credenciales ausentes o inválidas
403	Empresa bloqueada
404	Transacción o merchant no encontrado
409	Conflicto (duplicado o transacción inmutable)
422	Error de validación (campos inválidos)
429	Demasiadas solicitudes (límite: 100 por minuto por IP)
500	Error interno del servidor

---

Formato de las respuestas de error

Todas las respuestas de error siguen el mismo formato:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Descripción del error"
  }
}

---

Códigos de error posibles

Autenticación

Código	HTTP	Mensaje
UNAUTHORIZED	401	Missing or invalid Authorization header
UNAUTHORIZED	401	Invalid Basic Auth format
UNAUTHORIZED	401	Missing client_id or client_secret
UNAUTHORIZED	401	Invalid credentials
COMPANY_BLOCKED	403	Company is blocked

Validación

Código	HTTP	Mensaje
VALIDATION_ERROR	422	Mensaje del validador (ej.: card_last4 must be exactly 4 digits)

Transacciones

Código	HTTP	Mensaje
TRANSACTION_NOT_FOUND	404	Transaction not found
TRANSACTION_DUPLICATE	409	Transaction already exists
TRANSACTION_DUPLICATE	409	Another transaction with this external_source/external_id already exists
TRANSACTION_IMMUTABLE	409	Transaction cannot be modified: it has been used by a network event
MERCHANT_NOT_FOUND	404	Merchant not found

Rate limit

Código	HTTP	Mensaje
RATE_LIMIT_EXCEEDED	429	Rate limit exceeded, retry in X seconds

---

Errores en el envío por lotes

En el endpoint de batch, los errores individuales se devuelven en el array errors dentro de data, sin interrumpir el procesamiento de las demás transacciones:

{
  "data": {
    "created": 1,
    "failed": 2,
    "results": [
      { "external_id": "TXN-2026-001", "tx_id": "uuid-1", "warnings": [] }
    ],
    "errors": [
      { "index": 1, "external_id": "TXN-2026-002", "status": 409, "error": "Transaction already exists" },
      { "index": 2, "external_id": "TXN-2026-003", "status": 404, "error": "Merchant not found" }
    ]
  }
}

Cada error incluye:

• external_id: identifica qué transacción falló.
• status: código HTTP equivalente del error.
• error: mensaje descriptivo.