> ## 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 SPI
> Consulta los códigos de error que devuelve el riel Pix de SPI, el estado HTTP que lleva cada uno y qué hacer al respecto.
**Formato de error**
La API de SPI devuelve los errores como problem details de RFC 9457 con el tipo de medio `application/problem+json`:
```json JSON theme={null}
{
"type": "https://errors.lerian.studio/v1/SPI-1002",
"title": "Unprocessable Entity",
"status": 422,
"detail": "bacen rejected payment",
"code": "SPI-1002",
"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. El texto varía según la ocurrencia, así que decide la rama con `code`.
* **`code`** – Un identificador estable para la condición. Una solicitud que el riel rechazó antes de que llegara a un handler no lleva `code`. Esta API usa dos vocabularios aquí: los propios códigos `SPI-NNNN` del riel, y los tokens del directorio de claves Pix que se describen más adelante.
* **`errors`** – Lista opcional de detalles de validación por campo, cada uno con un `message`, una `location` y el `value` que causó el problema.
* **`correlationId`** – El identificador de correlación con alcance de la solicitud. Cita este valor en una solicitud de soporte.
En las respuestas `5xx`, el riel reemplaza `detail` por `internal error`, así que las causas internas no quedan expuestas. Usa `code` para decidir la rama de forma programática.
## Códigos del riel
***
Los códigos `SPI-NNNN` nombran las condiciones que el propio riel de SPI evalúa. El dígito después del prefijo los agrupa: `0` entrada, `1` transporte del riel, `2` autorización, `3` procesamiento, `4` límite de solicitudes y cuota, `9` reserva.
Cuatro códigos llevan más de un estado, porque la condición que nombran tiene más de una forma en este riel. Cada uno aparece abajo bajo cada estado con el que puede llegar.
Cuando BACEN rechaza un pago, el rechazo lleva el motivo de estado ISO 20022 propio de la red. `RJCT` es el que nombra un rechazo. En la superficie de la API, `SPI-1002` es el código para ese rechazo. Para encontrar qué pagos rechazó la red, consulta el informe de pagos rechazados. Enumera cada uno por estado terminal e id end-to-end.
### 401: No autenticado
***
| `code` | Descripción | `detail` |
| -------- | ------------------------------------------------------------------------------------------------ | ------------------------------- |
| SPI-2001 | La solicitud no identifica a un principal. El bearer está ausente, mal formado o no se reconoce. | authenticated actor unavailable |
### 403: Prohibido
***
| `code` | Descripción | `detail` |
| -------- | -------------------------------------------------------------------------------- | --------- |
| SPI-2002 | El emisor de la llamada está identificado y no está autorizado para esta acción. | forbidden |
### 404: No encontrado
***
| `code` | Descripción | `detail` |
| -------- | --------------------------------------------- | ----------------- |
| SPI-0010 | El recurso que nombra la solicitud no existe. | payment not found |
### 409: Conflicto
***
| `code` | Descripción | `detail` |
| -------- | ------------------------------------------------------------------------------------------- | --------------------------------------- |
| SPI-0011 | Ya existe un recurso con esta identidad. | participant already exists |
| SPI-3006 | El estado actual del ciclo de vida del recurso rechaza la operación. | payment is not eligible for return |
| SPI-3007 | Otro escritor cambió el recurso entre tu lectura y tu escritura. Vuelve a leer y reintenta. | participant status changed concurrently |
### 413: Payload demasiado grande
***
| `code` | Descripción | `detail` |
| -------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| SPI-0003 | La remessa subida supera lo que el canal de archivos por lotes procesa en una sola carga. Divide el archivo. | the remessa exceeds the 5 MB this channel processes in one upload |
### 422: No procesable
***
| `code` | Descripción | `detail` |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
| SPI-0001 | Una entrada obligatoria está ausente o vacía. | return reason is required |
| SPI-0002 | Un campo lleva el formato incorrecto. | mode must be FULL or INCREMENTAL |
| SPI-0003 | Una regla de negocio rechazó la solicitud. | invalid payment request |
| SPI-0011 | La superficie de cobros rechaza un identificador duplicado, como un txid que ya tiene otro cobro. | charge already exists |
| SPI-1002 | BACEN rechazó el mensaje. | bacen rejected payment |
| SPI-1011 | El directorio de claves Pix rechazó la solicitud. Cuando el directorio nombró el motivo, llega el token en su lugar. Consulta los tokens del directorio más abajo. | bacen dict rejected request |
| SPI-3002 | El procesamiento interno se negó a enrutar la solicitud. | operation routing decision unavailable |
| SPI-3006 | El ciclo de vida del cobro o del lote rechaza la operación. | invalid charge state transition |
| SPI-4001 | La cuota propia de operaciones del participante está agotada. | quota limit exceeded |
### 429: Demasiadas solicitudes
***
| `code` | Descripción | `detail` |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| SPI-4001 | La cuota de salida hacia BACEN del riel está agotada, o el directorio de claves Pix limitó la solicitud. Una limitación del directorio lleva la espera en el encabezado `Retry-After` cuando el directorio la prescribió. | bacen outbound quota exceeded |
### 500: Error del servidor
***
| `code` | Descripción | `detail` |
| -------- | --------------------------------------------------------------------------------------------------- | -------------- |
| SPI-9000 | Una falla interna inesperada. Reintenta y luego contacta a soporte con el valor de `correlationId`. | internal error |
### 502: Gateway incorrecto
***
| `code` | Descripción | `detail` |
| -------- | --------------------------------------------------------------------------------- | -------------- |
| SPI-1005 | La comunicación con BACEN falló por un motivo que el riel no pudo clasificar más. | internal error |
### 503: Servicio no disponible
***
Estos códigos nombran condiciones de dependencias. Aplica backoff y reintenta.
| `code` | Descripción | `detail` |
| -------- | ----------------------------------------------------------------------------------------------------------- | -------------- |
| SPI-1001 | El transporte de BACEN no está disponible. | internal error |
| SPI-1004 | Falló la validación de seguridad del transporte. El riel se negó a enviar por un canal que no pudo validar. | internal error |
| SPI-1010 | El directorio de claves Pix no está disponible, por mantenimiento o fuera de su ventana de servicio. | internal error |
| SPI-3001 | La persistencia o la publicación de eventos no está disponible. | internal error |
| SPI-9001 | Una dependencia downstream que la solicitud necesita no está disponible. | internal error |
### 504: Timeout del gateway
***
| `code` | Descripción | `detail` |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| SPI-1003 | BACEN no respondió dentro de la ventana del riel. El resultado no está determinado, así que consulta el recurso antes de reenviar. | internal error |
## Tokens del directorio de claves Pix
***
El directorio de claves Pix mantiene su propio vocabulario de errores, y el riel lo reenvía. Un rechazo del directorio te llega con el token propio del directorio en `code` y el estado HTTP propio del directorio en `status`. El URI de `type` lleva el mismo token como su último segmento.
Este vocabulario pertenece al directorio, así que trátalo como abierto. Maneja un token que no reconozcas por su `status`, y lee el token mismo como el motivo. Las tablas siguientes cubren los tokens que el riel maneja hoy, en el registro de claves, la búsqueda de claves, la eliminación de claves y las operaciones de reclamo.
Un rechazo por rate limit del directorio te llega como `SPI-4001` con HTTP 429. Cuando el directorio prescribió una espera, la respuesta la lleva en `Retry-After`. Consulta los códigos del riel más arriba.
### General
***
| `code` | Descripción | Estado |
| ----------------------- | -------------------------------------------------------------------------- | ------ |
| Forbidden | La solicitud viola una regla de autorización. | 403 |
| BadRequest | El formato de la solicitud no es válido en el nivel de esquema. | 400 |
| NotFound | La entidad que nombra la solicitud no existe. | 404 |
| Gone | El recurso existió y no está disponible. | 410 |
| InternalServerError | Una condición inesperada del lado del directorio. | 500 |
| ServiceUnavailable | El directorio no está disponible, por mantenimiento o fuera de su ventana. | 503 |
| RequestSignatureInvalid | La firma digital de la solicitud no es válida. | 400 |
| RequestIdAlreadyUsed | El mismo RequestId volvió a llegar con parámetros distintos. | 400 |
| InvalidReason | El motivo dado para la operación no es válido. | 400 |
| ParticipantInvalid | El participante no puede tomar parte en esta operación. | 400 |
| TaxIdNumberBlocked | El CPF o el CNPJ está bloqueado por orden judicial. | 400 |
### Registro de claves
***
| `code` | Descripción | Estado |
| --------------------------------------- | --------------------------------------------------------------------------------------------- | ------ |
| EntryInvalid | Los campos que crean o actualizan la entrada no son válidos. | 400 |
| EntryLimitExceeded | La cuenta ya tiene el número máximo de claves. | 400 |
| EntryAlreadyExists | La clave ya está registrada para este participante y propietario. | 400 |
| EntryCannotBeQueriedForBookTransfer | La clave pertenece al mismo PSP. Resuélvela internamente en lugar de a través del directorio. | 400 |
| EntryKeyOwnedByDifferentPerson | Otra persona es dueña de la clave. Abre un reclamo de posesión. | 400 |
| EntryKeyInCustodyOfDifferentParticipant | El mismo propietario tiene la clave en otro PSP. Abre un reclamo de portabilidad. | 400 |
| EntryTaxIdNumberByDifferentOwner | El CPF o el CNPJ de la entrada difiere del propietario de la clave. | 400 |
| EntryLockedByClaim | Un reclamo activo bloquea la entrada, así que no se puede eliminar. | 400 |
| EntryBlocked | Una orden judicial bloquea la entrada. | 400 |
### Reclamos de claves
***
| `code` | Descripción | Estado |
| -------------------------------- | ---------------------------------------------------------------------------- | ------ |
| ClaimInvalid | Los campos que crean o actualizan el reclamo no son válidos. | 400 |
| ClaimTypeInconsistent | El tipo de reclamo es inconsistente con el estado de la entrada. | 400 |
| ClaimKeyNotFound | La clave reclamada no tiene una entrada registrada. | 404 |
| ClaimAlreadyExistsForKey | Ya existe un reclamo activo para la clave. | 400 |
| ClaimResultingEntryAlreadyExists | La entrada resultante ya existe para el reclamante. | 400 |
| ClaimOperationInvalid | El estado del reclamo prohíbe la operación que solicitaste. | 400 |
| ClaimResolutionPeriodNotEnded | El período de resolución no ha terminado, así que la operación es prematura. | 400 |
| ClaimCompletionPeriodNotEnded | El período de finalización no ha terminado, así que finalizar es prematuro. | 400 |
## Rechazos de archivo de BR Code
***
El canal de archivos por lotes de BR Code responde a una remessa enviada línea por línea. Una línea aceptada liquida. Una línea rechazada lleva un código de rechazo de tres dígitos. También lleva el nombre de campo y la descripción que el esquema Pix publica para ese código. Tu conciliación mapea la respuesta contra la hoja de errores propia del esquema.
Dos rechazos rechazan una línea antes de que se ejecute cualquier regla de negocio, así que son los primeros que encuentra una integración nueva. `063` (Cadastro, Cliente nao cadastrado) dice que el encabezado del archivo nombra a un recebedor para el cual este despliegue no tiene un perfil registrado. `096` (Registro, Inválido) dice que el esquema rechazó el registro y no publica un código más específico para el campo en falta. Un registro de longitud incorrecta es uno de estos casos.
Otros cuatro cubren los dos identificadores que lleva la mayoría de las líneas. `012` (Chave pix, Chave inválida) dice que la línea cobra sobre una clave Pix para la cual este despliegue no tiene un recebedor registrado. `014` (Chave pix, Não é compatível com o cnpj ou agência e conta informada) nombra una clave registrada a otro recebedor. El encabezado del archivo resuelve a uno distinto. `016` (Identificador (txid), Em duplicidade) dice que el txid se repite. `017` (Identificador (txid), Inválido ou não encontrado) dice que el movimiento nombra un cobro que este riel no tiene.
La hoja de errores del esquema publica muchos más códigos. El canal renderiza el subconjunto sobre el que mapean sus propios rechazos. Cada línea rechazada nombra su campo, así que lee primero el nombre del campo y después el código.