Saltearse al contenido

Códigos de error

Los errores siempre vienen con esta forma:

{
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "Los datos enviados no son válidos.",
        "details": {
            "fields": {
                "amount": ["validation.required"]
            }
        }
    }
}

code — string estable, parsearlo programáticamente.
message — texto en español, está pensado para mostrar al usuario final del comercio si querés.
details — opcional, contexto extra (campos inválidos, info del provider, etc.).

Errores generales

Código	HTTP	Cuándo	Qué hacer
`UNAUTHENTICATED`	401	API key ausente o inválida.	Revisá el header `Authorization`.
`NOT_FOUND`	404	El recurso no existe o pertenece a otro tenant.	Verificá el `id`.
`VALIDATION_FAILED`	422	Los datos del request no pasaron validación.	Mirá `details.fields` para ver qué.
`RATE_LIMITED`	429	Superaste tu cuota de requests/min.	Esperá `Retry-After` segundos.
`INTERNAL_ERROR`	500	Algo nuestro falló.	Si persiste, escribinos.
`HTTP_ERROR`	varios	Error HTTP genérico.	Mirar el HTTP status code.

Errores de negocio (`BUSINESS_RULE`)

Código	HTTP	Cuándo
`INVALID_PAYMENT_STATE`	422	Pediste una acción incompatible con el estado actual del pago (ej. cancelar uno ya confirmado).
`INVALID_CARD_DATA`	422	La tarjeta no está catastrada o no tiene token.
`MISSING_PROVIDER_CREDENTIALS`	422	El tenant no tiene credenciales activas para el provider.
`MISSING_BANK_ACCOUNTS`	422	Intentaste crear un pago de transferencia sin cuentas bancarias configuradas.

Errores de provider (`PROVIDER_ERROR`)

Cuando el provider externo (Dinelco, Bancard) rechaza la operación, devolvemos:

{
    "error": {
        "code": "PROVIDER_ERROR",
        "message": "Mensaje legible en español",
        "provider": "dinelco",
        "reason": "settled"
    }
}

En entorno test, además incluimos error.detail con el mensaje técnico literal del proveedor (sin traducir). En live, no.

Errores de Dinelco mapeados

`responseCode` Dinelco	Significado	Notas
`0000`	Aprobado.	Éxito (no es error).
`TOKEN_TYPE_NOT_SUPPORTED`	Tarjeta inválida o número no aceptado.	En test, usar las tarjetas de prueba.
`90019`	Pago ya liquidado, no se puede reversar.	La marca lo procesó. Coordinar manual fuera del gateway. Ver reversa.

A medida que aparezcan códigos nuevos en pruebas reales, los iremos agregando acá. Si te aparece uno no listado, mirá error.detail (en test) o pediinos contexto.

Webhook delivery — qué considerar error

Esto NO es un error que vos consumís de la API; es lo que vos devolvés a un webhook nuestro:

Tu HTTP status	Qué hacemos
`2xx`	OK, marcamos delivered.
`4xx`	No reintentamos.
`5xx` o timeout (>10s)	Reintentamos con backoff (ver reintentos).