Lista de errores de Payments

Busca cualquier código de error de Payments, el estado HTTP con el que llega y la condición que nombra, para que puedas bifurcar el flujo de una solicitud fallida.

Formato del error

La API de Payments responde cada solicitud fallida con un documento de problema RFC 9457 en el tipo de medio application/problem+json, sin importar qué endpoint llamaste ni dónde capture el servicio la falla. Una solicitud que supera el límite de tasa responde 429 con PBP-0009.

Problem document

{
  "type": "https://errors.lerian.studio/v1/PBP-0101",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "bankslip digitable line must have 47 digits",
  "code": "PBP-0101"
}

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í.
• instance – El identificador de rastreo de la solicitud, cuando lo tiene.

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.

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.

code	Descripción	Estado
PBP-0001	Solicitud malformada, o un campo que no pasa la validación	400
PBP-0002	Una condición inesperada dentro del servicio	500
PBP-0003	El servicio no pudo determinar quién llama	401
PBP-0004	Quien llama no puede hacer esta acción	403
PBP-0005	El recurso indicado en la solicitud no existe	404
PBP-0006	Una regla rechaza una solicitud bien formada, incluida una capacidad que esta versión de la API no ofrece	422
PBP-0007	La solicitud entra en conflicto con el estado del recurso, o con una solicitud aún en curso	409
PBP-0008	Una dependencia que esta operación necesita no respondió	503
PBP-0009	Se superó el límite de tasa de solicitudes de todo el servicio	429
PBP-0010	El cuerpo de la solicitud supera el límite de tamaño	413
PBP-0012	La operación necesita una clave de idempotencia, y la solicitud no incluye ninguna o incluye una que no es un UUID válido	400
PBP-0013	La clave de idempotencia pertenece a una solicitud anterior que difiere de esta	422
PBP-0017	La cuenta del proveedor para este tenant no está completamente configurada	422
PBP-0019	La ruta existe, y no acepta este método HTTP	405
PBP-0020	El cuerpo de la solicitud no llegó a tiempo	408
PBP-0022	La operación no acepta el tipo de contenido que enviaste	415
PBP-0023	Una falla del lado de quien llama que no lleva código propio	400
PBP-0025	El header X-Organization-Id falta o no es un UUID válido	400
PBP-0026	El miembro ledgerId falta o no es un UUID válido	400

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.

code	Descripción	Estado
PBP-0014	El proveedor de pagos leyó la instrucción y la rechazó	422
PBP-0015	El proveedor de pagos no está disponible	503
PBP-0016	El proveedor respondió con algo que este servicio no puede usar	502
PBP-0113	El proveedor respondió la consulta previa al pago con un formato que este servicio no puede usar	502
PBP-0114	La fuente de la factura no está disponible temporalmente para la consulta de facturas	503
PBP-0211	El proveedor de pagos no recibió la instrucción de pago, y no se pagó nada	503

Errores de boleto

---

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

code	Descripción	Estado
PBP-0102	La solicitud de serie de cuotas falla en la validación	422
PBP-0103	El boleto está en un estado que la cancelación no acepta	422
PBP-0105	El PDF del boleto todavía no está listo en el proveedor	503
PBP-0106	La emisión de boleto no puede verificar la cuenta de fondeo en este despliegue	422
PBP-0107	El proveedor no tiene registro del boleto que indica esta cancelación	422
PBP-0108	El nosso número ya está en uso en la cuenta del proveedor	422
PBP-0116	La cuenta emisora no tiene titular registrado, o el registro del titular está incompleto, por lo que no se puede establecer el beneficiario final	400
PBP-0117	El titular registrado no puede usarse como beneficiario final del boleto	422
PBP-0118	No se pudo leer el registro del titular, o la lectura no está configurada, por lo que no se puede establecer el beneficiario final	503
PBP-0119	El pagador es el titular de la cuenta, que es el beneficiario final del boleto	422
PBP-0120	Un boleto híbrido no tiene un receptor Pix que se pueda usar	422
PBP-0121	Se rechaza la adopción del título del proveedor de una cuota, y no se escribe nada	422
PBP-0122	Un lote de boletos tiene menos de 1 o más de 25 ítems	422
PBP-0123	Uno o más ítems de un lote de boletos incumplen una regla, y no se emite nada del lote	422
PBP-0125	Dos o más ítems de un lote de boletos tienen el mismo nosso número. Aparece solo dentro de itemErrors del PBP-0123	422

Errores de pago

---

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

code	Descripción	Estado
PBP-0100	La línea digitable no pasa la suma de verificación FEBRABAN	422
PBP-0101	La línea digitable no tiene la cantidad de dígitos que exige su tipo de pago	422
PBP-0110	La fuente no tiene ningún boleto bancario con esta línea digitable	404
PBP-0111	La fuente rechazó la línea por un motivo propio	422
PBP-0112	Quien llama superó el rate limit de la consulta de facturas	429
PBP-0200	Los campos del DARF no pasan la validación	400
PBP-0202	El inicio del pago no puede verificar la cuenta de fondeo en este despliegue	422
PBP-0203	La operación de cancelación de pago rechaza todas las solicitudes	501
PBP-0204	El registro del titular de la cuenta de fondeo falta o está incompleto, así que no se puede determinar el pagador	400
PBP-0205	El registro del titular de la cuenta de fondeo es inconsistente, así que no se puede determinar el pagador	422
PBP-0206	No se pudo acceder a los registros que identifican al titular de la cuenta de fondeo	503
PBP-0207	El nombre del titular de la cuenta de fondeo es más largo de lo que admite un DARF	422
PBP-0208	El documento fiscal del titular de la cuenta de fondeo no tiene solo dígitos	422
PBP-0210	La consulta previa al pago del proveedor dice que la factura no se puede pagar	422

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.

code	Descripción	Estado
PBP-0300	La cuenta de fondeo no tiene el saldo disponible que la escritura necesita	422
PBP-0301	El ledger no completó su etapa, o el servicio no pudo registrar el pago y no lo envió al proveedor	503
PBP-0302	La escritura llevaría la cuenta de fondeo más allá de su límite de sobregiro	422

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.

code	Descripción	Estado
PBP-0400	La URL de callback no es válida, o este despliegue la bloquea	400
PBP-0401	El secreto de firma es más corto que la longitud mínima que esta API acepta	400
PBP-0402	La lista de eventos está ausente, o nombra un tipo de evento que esta API no publica	400

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.

code	Descripción	Estado
PBP-0500	La firma de la entrega no se autenticó	401
PBP-0501	El cuerpo de la entrega está ausente, no se puede analizar, o no respeta el esquema del envelope	400
PBP-0502	El cuerpo de la entrega supera el límite del endpoint	413
PBP-0503	Un miembro obligatorio del envelope llega presente pero vacío	400