Códigos de error
Códigos HTTP
Sección titulada «Códigos HTTP»| Código | Significado |
|---|---|
| 200 | Éxito (GET, PATCH, batch) |
| 201 | Transacción creada (POST individual) |
| 401 | Credenciales ausentes o inválidas |
| 403 | Empresa bloqueada, o ningún producto que usa transacciones activo (solo en la creación) |
| 404 | Transacción o merchant no encontrado |
| 405 | Las transacciones no se pueden eliminar (DELETE), ver Eliminar transacción |
| 409 | Conflicto (duplicado, o actualización de 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
Sección titulada «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
Sección titulada «Códigos de error posibles»Autenticación
Sección titulada «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
Sección titulada «Validación»| Código | HTTP | Mensaje |
|---|---|---|
VALIDATION_ERROR | 422 | Mensaje del validador (ej.: card_last4 must be exactly 4 digits) |
Transacciones
Sección titulada «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 |
TRANSACTION_DELETE_NOT_ALLOWED | 405 | Transactions cannot be deleted |
MERCHANT_NOT_FOUND | 404 | Merchant not found |
PRODUCT_NOT_ACTIVE | 403 | Transactions require an active Prevention or Dispute product |
PRODUCT_NOT_ACTIVE solo aparece en la creación (POST /transactions y POST /transactions/batch), cuando la empresa no tiene Prevención ni Disputa activa. Consultar y actualizar no exigen producto activo. Ver Quién envía transacciones.
Rate limit
Sección titulada «Rate limit»| Código | HTTP | Mensaje |
|---|---|---|
RATE_LIMIT_EXCEEDED | 429 | Rate limit exceeded, retry in X seconds |
Errores en el envío por lotes
Sección titulada «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" } ] }}La excepción es el 403 PRODUCT_NOT_ACTIVE: sin Prevención ni Disputa activa, la llamada entera se rechaza con 403 y no se crea ninguna transacción. No aparece en el array errors.
Cada error incluye:
index: posición de la fila en el array que enviaste, empezando en cero.external_id: identifica qué transacción falló.status: código HTTP equivalente del error.error: mensaje descriptivo.