> ## 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 SPB
> Consulta cualquier código de error de SPB, el estado HTTP que lo responde y el vocabulario de rechazo que devuelve la red de BACEN.
**Formato de error**
SPB devuelve los errores como problem details de RFC 9457. La referencia de la API declara el tipo de medio `application/problem+json` y el esquema `Detail` para estas respuestas.
```json JSON theme={null}
{
"type": "https://errors.lerian.studio/v1/SPB-0003",
"title": "Unprocessable Entity",
"status": 422,
"detail": "validation failed",
"code": "SPB-0003",
"correlationId": "req-7a3f9c2e"
}
```
**Definiciones de campos**
* **`type`** – Un URI que identifica el error en el catálogo de errores de Lerian, construido como `https://errors.lerian.studio/v1/`. Una respuesta sin `code` lleva el valor predeterminado de RFC `about:blank`.
* **`title`** – El texto del estado HTTP, por ejemplo `Unprocessable Entity`.
* **`status`** – El código de estado HTTP.
* **`detail`** – Una explicación legible de esta ocurrencia. En la mayoría de las respuestas `5xx`, SPB reemplaza el texto por `internal error`, así que la causa interna no queda expuesta en la respuesta. Usa `code` para decidir la rama en su lugar.
* **`code`** – El código de error estable de SPB, con el formato `SPB-NNNN`. Una solicitud que el enrutador rechaza, o que falla la validación del esquema de la solicitud, no lleva `code`.
* **`errors`** – Una lista opcional de detalles de validación por campo. Cada entrada lleva un `message` y una `location`.
* **`correlationId`** – El identificador de correlación con alcance de la solicitud, cuando SPB resolvió uno. Cita este valor en una solicitud de soporte.
El estado HTTP depende de la capa que rechaza la solicitud. Una solicitud que llega al handler y luego infringe una regla de negocio responde con el estado que aparece en las tablas siguientes. La capa de idempotencia se ejecuta antes del handler. Una solicitud que esa capa rechaza por una clave ausente o mal formada responde `400 Bad Request`. Una repetición de una clave todavía en curso responde `409 Conflict`.
La columna `detail` resume el texto que SPB coloca en el campo `detail`. La redacción exacta depende del punto de llamada, porque un punto de llamada puede agregarle contexto específico de la solicitud.
## Errores de validación y de entrada
***
El rango `SPB-0xxx` cubre una solicitud que SPB leyó y luego rechazó.
### HTTP 422 Entidad no procesable
| `code` | Descripción | `detail` |
| -------- | ------------------------------------------- | -------------------- |
| SPB-0001 | Entrada obligatoria ausente o inválida | invalid input |
| SPB-0002 | Formato de campo inválido | invalid field format |
| SPB-0003 | Falló la validación de una regla de negocio | validation failed |
### HTTP 413 Entidad de solicitud demasiado grande
| `code` | Descripción | `detail` |
| -------- | ------------------------------------------------------ | ----------------- |
| SPB-0004 | El cuerpo de la solicitud supera el límite configurado | payload too large |
### HTTP 404 No encontrado
| `code` | Descripción | `detail` |
| -------- | --------------------- | ------------------ |
| SPB-0010 | Recurso no encontrado | resource not found |
### HTTP 409 Conflicto
| `code` | Descripción | `detail` |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| SPB-0011 | Recurso duplicado. Una repetición que llega mientras la solicitud original todavía está en curso también responde con este código. | request is already being processed |
## Errores de autenticación y de autorización
***
El rango `SPB-2xxx` cubre una solicitud cuya credencial está ausente o no se puede usar, y una solicitud que pide una acción fuera de sus permisos.
### HTTP 401 No autorizado
| `code` | Descripción | `detail` |
| -------- | ------------------------- | ----------------------- |
| SPB-2001 | Se requiere autenticación | authentication required |
### HTTP 403 Prohibido
| `code` | Descripción | `detail` |
| -------- | ------------------------------------------------------------------ | -------------- |
| SPB-2002 | El emisor de la llamada no está autorizado para la acción | not authorized |
| SPB-2003 | La solicitud usó HTTP en texto plano donde el despliegue exige TLS | HTTPS required |
## Errores de procesamiento y de estado
***
El rango `SPB-3xxx` cubre una solicitud que SPB aceptó y luego no pudo aplicar. Tres de estos códigos describen un conflicto de estado sobre el que puedes actuar, así que responden `409` en lugar de un `5xx`.
### HTTP 409 Conflicto
| `code` | Descripción | `detail` |
| -------- | --------------------------------------------------------------------------- | --------------------------------------------------- |
| SPB-3004 | La readiness del servicio bloquea el comando | service is not ready for the requested operation |
| SPB-3006 | El estado del ciclo de vida de la operación no permite la acción solicitada | operation state does not allow the requested action |
| SPB-3007 | El reintento solicitado entra en conflicto con el estado actual del recurso | retry conflicts with current resource state |
### HTTP 500 Error interno del servidor
| `code` | Descripción | `detail` |
| -------- | --------------------- | -------------- |
| SPB-3001 | Falla de persistencia | internal error |
## Errores de rate limit
***
El rango `SPB-4xxx` cubre a un emisor de llamadas que superó su presupuesto de solicitudes.
### HTTP 429 Demasiadas solicitudes
| `code` | Descripción | `detail` |
| -------- | ---------------------------------------------------------------------- | ------------------- |
| SPB-4001 | Se superó el rate limit. Reintenta después de un intervalo de backoff. | rate limit exceeded |
## Errores de reserva
***
El rango `SPB-9xxx` cubre una falla del lado de Lerian o en un componente del que depende SPB. Reintenta una solicitud que responde `503` o `504`. Para los demás códigos, cita el `correlationId` en una solicitud de soporte.
### HTTP 500 Error interno del servidor
| `code` | Descripción | `detail` |
| -------- | ------------------------------------- | -------------- |
| SPB-9000 | Error interno del servidor inesperado | internal error |
| SPB-9003 | Falla en el pipeline de mensajes | internal error |
### HTTP 503 Servicio no disponible
| `code` | Descripción | `detail` |
| -------- | --------------------------------------------- | -------------- |
| SPB-9001 | Una dependencia downstream no está disponible | internal error |
### HTTP 504 Tiempo de espera del gateway agotado
| `code` | Descripción | `detail` |
| -------- | --------------------------------------- | -------------- |
| SPB-9002 | La operación superó el tiempo de espera | internal error |
## Rechazos de la red de BACEN
***
Un código `SPB-NNNN` describe una decisión que tomó Lerian SPB. Un mensaje que SPB transmite todavía puede fallar en el STR, y ese rechazo lleva el vocabulario propio de BACEN en lugar de un código `SPB-NNNN`.
`GET /v1/str/reports/rejected` lista los mensajes rechazados para un rango de fechas. Cada elemento rechazado lleva un campo `rejectReason` cuando BACEN suministró uno. El valor es el propio código de error de BACEN para el rechazo, proyectado sin cambios. SPB lo lee del campo de código de error en la devolución de error del STR que envía BACEN.
Trata `rejectReason` como un vocabulario abierto. El conjunto de valores pertenece a BACEN, y crece junto con el catálogo del STR. Pasa el valor a tu operador en lugar de compararlo con una lista fija en tu cliente.
El resultado de la liquidación viaja por separado, en el campo `sitLancSTR` de una operación. SPB proyecta el estado de liquidación del STR de forma literal en ese campo. El campo permanece vacío hasta que el STR liquida la operación.