Skip to main content
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. La capa de autenticación y autorización se ejecuta antes que todo lo demás y responde en texto plano con un motivo simple y sin código de error. Una falla que el pipeline de solicitudes detecta después, antes de que la capa de API la vea, responde con un cuerpo JSON plano en application/json. La verificación de idempotencia es la regla del pipeline que encuentras con más frecuencia. Todo lo que la capa de API detecta responde con un documento de problema RFC 9457 en el tipo de medio application/problem+json.
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, con el formato PBP-NNNN. 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. El miembro code tiene el mismo valor PBP-NNNN en ambos cuerpos JSON. Bifurca la lógica según ese código, y maneja los casos 401 y 403 según el estado, porque un rechazo de la capa de autenticación no lleva código. 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. Guíate por el tipo de medio en lugar del código para diferenciar los dos cuerpos, porque el pipeline también responde así ante una falla que ningún handler capturó, y esa falla puede nombrar cualquier código.

​
Errores de plataforma

Estos códigos responden en cualquier endpoint. La capa de transporte y el pipeline de solicitudes compartido los generan, así que manéjalos en cada riel.

​
Errores del proveedor

Tres códigos llevan la respuesta del proveedor de pagos sobre una instrucción de pago. PBP-0014 significa que el proveedor leyó la instrucción y la rechazó, así que corrige la causa antes de enviar una nueva solicitud. Para PBP-0015 y PBP-0016 el proveedor no dio una respuesta utilizable. PBP-0014 se genera antes de que esta API escriba algo, así que reintentar con la misma clave de idempotencia es seguro. PBP-0015 y PBP-0016 dejan el resultado sin determinar, así que reintenta esos con una nueva clave de idempotencia.

​
Errores de boleto

Estos códigos responden en el riel de boleto: emisión, serie de 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 y DARF.

​
Errores del ledger

Tres códigos llevan la respuesta del ledger a una escritura, y lo que importa es si el ledger respondió o no. PBP-0300 y PBP-0302 son rechazos: la escritura falló, así que corrige la causa y envía una nueva solicitud. PBP-0301 indica que el ledger no dio ninguna respuesta: el pago existe, así que no envíes nada y consúltalo en su lugar.

​
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.