> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 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`.
```json Problem document theme={null}
{
"type": "https://errors.lerian.studio/v1/PBP-0101",
"title": "Unprocessable Entity",
"status": 422,
"detail": "bankslip digitable line must have 47 digits",
"code": "PBP-0101"
}
```
```json Flat body theme={null}
{
"code": "PBP-0013",
"title": "Idempotency Key Conflict",
"message": "The request body does not match the original request for this idempotency key."
}
```
**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/`.
* **`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.
| `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 recibió la solicitud y no pudo determinar quién es el cliente. Un rechazo de la capa de autenticación responde en texto plano y no lleva código | 401 |
| 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 | El cliente superó el límite de frecuencia de solicitudes | 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 | 400 |
| PBP-0013 | La clave de idempotencia pertenece a una solicitud anterior con un cuerpo distinto | 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 del cliente que no lleva código propio | 400 |
## 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.
| `code` | Descripción | Estado |
| -------- | --------------------------------------------------------------- | ------ |
| PBP-0014 | El proveedor de pagos leyó la instrucción y la rechazó | 422 |
| PBP-0015 | El proveedor de pagos está temporalmente inaccesible | 503 |
| PBP-0016 | El proveedor respondió con algo que este servicio no puede usar | 502 |
## Errores de boleto
***
Estos códigos responden en el riel de boleto: emisión, serie de cuotas, cancelación y obtención del PDF.
| `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-0102 | El plan de cuotas no pasa 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 |
## Errores de pago
***
Estos códigos responden en el riel de pago de facturas: bankslip, servicios públicos y DARF.
| `code` | Descripción | Estado |
| -------- | ---------------------------------------------------------------------------- | ------ |
| PBP-0200 | Los campos del DARF no pasan la validación | 400 |
| PBP-0201 | El pago está en un estado que la cancelación no acepta | 422 |
| PBP-0202 | El inicio del pago no puede verificar la cuenta de fondeo en este despliegue | 422 |
| PBP-0203 | La cancelación de pago no está implementada en esta versión de la API | 501 |
## 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.
| `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 dio ninguna respuesta, así que el resultado de la escritura queda sin determinar | 503 |
| PBP-0302 | El ledger respondió y rechazó la escritura por una regla de negocio | 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 |