Saltar al contenido principal
Formato del error La API de Payments responde a una solicitud fallida con uno de tres cuerpos. El cuerpo que recibes depende de dónde el servicio detecta la falla, no del endpoint que llamaste. Una falla que el pipeline de solicitudes detecta antes de que la capa de API la vea responde con un cuerpo JSON plano en application/json. El pipeline autentica a quien llama (PBP-0003 en 401) y autoriza la acción (PBP-0004 en 403). También abre el almacenamiento del tenant (PBP-0008 en 503) y ejecuta la verificación de idempotencia. Todo lo que la capa de API detecta responde con un documento de problema RFC 9457 en el tipo de medio application/problem+json. El limitador de frecuencia de todo el servicio responde 429 con el texto plano Too Many Requests y sin código de error.
Definiciones de los campos
  • type – Un URI que identifica el error en el catálogo de errores de Lerian. Se construye como https://errors.lerian.studio/v1/<code>.
  • title – El texto del estado HTTP, por ejemplo Unprocessable Entity.
  • status – El código de estado HTTP.
  • detail – Texto sobre esta ocurrencia de la condición. La redacción proviene de la rama que la generó.
  • code – Un identificador estable para la condición. Bifurca la lógica según este valor.
  • errors – Lista opcional de detalles de validación por campo, cada uno con un message, una location y el value encontrado ahí.
En los estados 500, 502 y 503 el miembro detail lleva un texto fijo en lugar de una descripción de tu solicitud, así que lee code para identificar la condición. El cuerpo plano lleva code, title, message y un objeto details opcional. Nunca lleva type, status ni detail. Cinco códigos llegan como cuerpo plano cuando la verificación de idempotencia los genera: PBP-0002, PBP-0007, PBP-0008, PBP-0012 y PBP-0013. El pipeline también responde así ante una falla que ningún handler capturó. Por eso, guíate por el tipo de medio en lugar del código para diferenciar los dos cuerpos.

​
Errores de plataforma

Estos códigos no son específicos de un riel. La capa de transporte, el pipeline de solicitudes y los handlers los generan.

​
Errores del proveedor

Estos códigos llevan la respuesta del proveedor de pagos. Lo que es seguro reenviar depende de la operación, así que lee las descripciones de error de la operación en la referencia de la API antes de reenviar.

​
Errores de boleto

Estos códigos responden en el riel de boleto: emisión, cuotas, cancelación y obtención del PDF.

​
Errores de pago

Estos códigos responden en el riel de pago de facturas: bankslip, servicios públicos, DARF y la consulta de facturas.

​
Errores del ledger

Estos códigos llevan el lado del ledger en un pago. Lo que es seguro reenviar depende de la operación, así que lee las descripciones de error de la operación en la referencia de la API antes de reenviar.

​
Errores de configuración de webhook

Estos códigos responden a una solicitud que configura hacia dónde envía esta API las notificaciones de eventos.

​
Errores del webhook entrante del proveedor

Estos cuatro códigos responden al proveedor de pagos que publica eventos de liquidación en el endpoint del webhook. Le indican al proveedor qué corrección necesita su entrega.