Errores

Una sola forma de error en toda la API.

Todos los errores comparten la misma estructura. Siempre.

JSON

{
  "error": {
    "type": "provider_error",
    "code": "card_declined",
    "message": "The card was declined.",
    "param": "payment_method",
    "doc_url": "https://docs.cauril.com/errors/card_declined",
    "request_id": "req_01J...",
    "provider_error": { "provider": "stripe", "raw_code": "card_declined" }
  }
}

Campo	Descripción
`type`	Categoría del error (ver tabla abajo).
`code`	Código específico y estable, apto para `switch` en tu código.
`message`	Texto legible para humanos. No lo parsees; usá `code`.
`param`	El campo que causó el error, si aplica.
`doc_url`	Link a la documentación de ese código.
`request_id`	Identificador de la request, útil para soporte.
`provider_error`	Detalle crudo del PSP, cuando el error vino de él.

Tipos y status HTTP

`type`	HTTP	Cuándo
`invalid_request_error`	400 / 422	Body o parámetros inválidos.
`authentication_error`	401	API key faltante o inválida.
`permission_error`	403	La key no tiene permiso para el recurso.
`not_found_error`	404	El recurso no existe (o no es de tu organización).
`idempotency_error`	409	`Idempotency-Key` reusada con otro body.
`conflict_error`	409	El estado actual no permite la operación (ej. reembolsar un pago no exitoso).
`rate_limit_error`	429	Demasiadas requests.
`provider_error`	402	El PSP rechazó o falló la operación (ej. tarjeta declinada).
`api_error`	500	Algo falló de nuestro lado.

Transitorios vs. permanentes

Un provider_error puede ser permanente (una tarjeta declinada va a declinar de nuevo → no reintentes igual) o transitorio (un 5xx o 429 del PSP → reintentá con la misma Idempotency-Key). Los errores api_error (5xx) también son transitorios.

Nunca tomes decisiones de negocio a partir del message (puede cambiar). Usá siempre type + code.