> ## 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 erros do SPI
> Consulte os códigos de erro que o trilho Pix do SPI retorna, o status HTTP que cada um carrega e o que fazer a respeito.
**Formato de erro**
A API do SPI retorna erros como problem details da RFC 9457, com o media type `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"
}
```
**Definições de campo**
* **`type`** – Um URI que identifica o erro no catálogo de erros da Lerian, construído como `https://errors.lerian.studio/v1/`. Uma resposta sem `code` carrega o padrão da RFC `about:blank`.
* **`title`** – O texto do status HTTP (por exemplo, `Unprocessable Entity`).
* **`status`** – O código de status HTTP.
* **`detail`** – Uma explicação legível para essa ocorrência. O texto varia conforme a ocorrência, então decida com base em `code`.
* **`code`** – Um identificador estável para a condição. Uma requisição que o trilho recusou antes de chegar a um handler não carrega `code`. Essa API usa dois vocabulários aqui: os próprios códigos `SPI-NNNN` do trilho, e os tokens do diretório de chaves Pix descritos mais adiante.
* **`errors`** – Lista opcional de detalhes de validação por campo, cada um com uma `message`, uma `location` e o `value` responsável.
* **`correlationId`** – O identificador de correlação da requisição. Cite esse valor em uma solicitação de suporte.
Para respostas `5xx`, o trilho substitui `detail` por `internal error`, então as causas internas ficam de fora. Use `code` para decidir de forma programática.
## Códigos do trilho
***
Os códigos `SPI-NNNN` nomeiam condições que o próprio trilho SPI julga. O dígito após o prefixo os agrupa: `0` entrada, `1` transporte do trilho, `2` autorização, `3` processamento, `4` taxa e cota, `9` fallback.
Quatro códigos carregam mais de um status, porque a condição que nomeiam tem mais de uma forma nesse trilho. Cada um aparece abaixo, sob cada status com que pode chegar.
Quando o BACEN recusa um pagamento, a recusa carrega o motivo de status ISO 20022 próprio da rede. `RJCT` é o que nomeia uma recusa. Na superfície da API, `SPI-1002` é o código dessa recusa. Para descobrir quais pagamentos a rede recusou, leia o relatório de pagamentos rejeitados. Ele lista cada um por status terminal e end-to-end id.
### 401: Não autenticado
***
| `code` | Descrição | `detail` |
| -------- | ----------------------------------------------------------------------------------------------- | ------------------------------- |
| SPI-2001 | A requisição não identifica um principal. O bearer está ausente, malformado ou não reconhecido. | authenticated actor unavailable |
### 403: Proibido
***
| `code` | Descrição | `detail` |
| -------- | --------------------------------------------------------------------- | --------- |
| SPI-2002 | O solicitante está identificado e não está autorizado para essa ação. | forbidden |
### 404: Não encontrado
***
| `code` | Descrição | `detail` |
| -------- | --------------------------------------------- | ----------------- |
| SPI-0010 | O recurso que a requisição nomeia não existe. | payment not found |
### 409: Conflito
***
| `code` | Descrição | `detail` |
| -------- | ------------------------------------------------------------------------------------------------- | --------------------------------------- |
| SPI-0011 | Já existe um recurso com essa identidade. | participant already exists |
| SPI-3006 | O estado atual do ciclo de vida do recurso recusa a operação. | payment is not eligible for return |
| SPI-3007 | Outro gravador alterou o recurso entre sua leitura e sua escrita. Leia novamente e tente de novo. | participant status changed concurrently |
### 413: Payload muito grande
***
| `code` | Descrição | `detail` |
| -------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| SPI-0003 | A remessa enviada excede o que o canal de arquivo em lote processa em um único upload. Divida o arquivo. | the remessa exceeds the 5 MB this channel processes in one upload |
### 422: Não processável
***
| `code` | Descrição | `detail` |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
| SPI-0001 | Uma entrada obrigatória está ausente ou vazia. | return reason is required |
| SPI-0002 | Um campo carrega o formato errado. | mode must be FULL or INCREMENTAL |
| SPI-0003 | Uma regra de negócio recusou a requisição. | invalid payment request |
| SPI-0011 | A superfície de cobrança recusa um identificador duplicado, como um txid que outra cobrança já possui. | charge already exists |
| SPI-1002 | O BACEN rejeitou a mensagem. | bacen rejected payment |
| SPI-1011 | O diretório de chaves Pix rejeitou a requisição. Quando o diretório nomeou o motivo, o token chega no lugar. Veja os tokens do diretório abaixo. | bacen dict rejected request |
| SPI-3002 | O processamento interno recusou rotear a requisição. | operation routing decision unavailable |
| SPI-3006 | O ciclo de vida da cobrança ou do lote recusa a operação. | invalid charge state transition |
| SPI-4001 | A própria cota de operação do participante está esgotada. | quota limit exceeded |
### 429: Muitas requisições
***
| `code` | Descrição | `detail` |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| SPI-4001 | A cota de saída para o BACEN do trilho está esgotada, ou o diretório de chaves Pix limitou a taxa da requisição. Uma limitação do diretório carrega a espera no header `Retry-After` quando o diretório prescreveu uma. | bacen outbound quota exceeded |
### 500: Erro do servidor
***
| `code` | Descrição | `detail` |
| -------- | --------------------------------------------------------------------------------------------------------------------- | -------------- |
| SPI-9000 | Uma falha interna inesperada. Tente novamente e depois entre em contato com o suporte com o valor de `correlationId`. | internal error |
### 502: Gateway inválido
***
| `code` | Descrição | `detail` |
| -------- | --------------------------------------------------------------------------------------------- | -------------- |
| SPI-1005 | A comunicação com o BACEN falhou por um motivo que o trilho não conseguiu classificar melhor. | internal error |
### 503: Serviço indisponível
***
Esses códigos nomeiam condições de dependência. Recue e tente novamente.
| `code` | Descrição | `detail` |
| -------- | ------------------------------------------------------------------------------------------------------------- | -------------- |
| SPI-1001 | O transporte do BACEN está indisponível. | internal error |
| SPI-1004 | A validação de segurança do transporte falhou. O trilho recusou enviar em um canal que não conseguiu validar. | internal error |
| SPI-1010 | O diretório de chaves Pix está indisponível, por manutenção ou fora da sua janela de serviço. | internal error |
| SPI-3001 | A persistência ou a publicação de eventos está indisponível. | internal error |
| SPI-9001 | Uma dependência downstream de que a requisição precisa está indisponível. | internal error |
### 504: Timeout do gateway
***
| `code` | Descrição | `detail` |
| -------- | -------------------------------------------------------------------------------------------------------------------------- | -------------- |
| SPI-1003 | O BACEN não respondeu dentro da janela do trilho. O resultado é indeterminado, então consulte o recurso antes de reenviar. | internal error |
## Tokens do diretório de chaves Pix
***
O diretório de chaves Pix mantém seu próprio vocabulário de erro, e o trilho o repassa. Uma recusa do diretório chega até você com o próprio token do diretório em `code` e o próprio status HTTP do diretório em `status`. O URI `type` carrega o mesmo token como seu último segmento.
Esse vocabulário pertence ao diretório, então trate-o como aberto. Trate um token que você não reconhece pelo seu `status`, e leia o próprio token como o motivo. As tabelas abaixo cobrem os tokens que o trilho lida hoje, em registro de chave, consulta de chave, exclusão de chave e as operações de reivindicação.
Uma recusa de limitação de taxa do diretório chega até você como `SPI-4001` com HTTP 429. Quando o diretório prescreveu uma espera, a resposta a carrega em `Retry-After`. Veja os códigos do trilho acima.
### Geral
***
| `code` | Descrição | Status |
| ----------------------- | -------------------------------------------------------------------- | ------ |
| Forbidden | A requisição viola uma regra de autorização. | 403 |
| BadRequest | O formato da requisição é inválido no nível de schema. | 400 |
| NotFound | A entidade que a requisição nomeia não existe. | 404 |
| Gone | O recurso existiu e não está disponível. | 410 |
| InternalServerError | Uma condição inesperada do lado do diretório. | 500 |
| ServiceUnavailable | O diretório está indisponível, por manutenção ou fora da sua janela. | 503 |
| RequestSignatureInvalid | A assinatura digital da requisição é inválida. | 400 |
| RequestIdAlreadyUsed | O mesmo RequestId voltou com parâmetros diferentes. | 400 |
| InvalidReason | O motivo informado para a operação é inválido. | 400 |
| ParticipantInvalid | O participante não pode fazer parte dessa operação. | 400 |
| TaxIdNumberBlocked | O CPF ou CNPJ está bloqueado por ordem judicial. | 400 |
### Registro de chave
***
| `code` | Descrição | Status |
| --------------------------------------- | ------------------------------------------------------------------------------------------ | ------ |
| EntryInvalid | Os campos que criam ou atualizam a entrada são inválidos. | 400 |
| EntryLimitExceeded | A conta já possui o número máximo de chaves. | 400 |
| EntryAlreadyExists | A chave já está registrada para esse participante e proprietário. | 400 |
| EntryCannotBeQueriedForBookTransfer | A chave pertence ao mesmo PSP. Resolva-a internamente em vez de pelo diretório. | 400 |
| EntryKeyOwnedByDifferentPerson | Uma pessoa diferente é dona da chave. Abra uma reivindicação de posse. | 400 |
| EntryKeyInCustodyOfDifferentParticipant | O mesmo proprietário mantém a chave em outro PSP. Abra uma reivindicação de portabilidade. | 400 |
| EntryTaxIdNumberByDifferentOwner | O CPF ou CNPJ na entrada difere do proprietário da chave. | 400 |
| EntryLockedByClaim | Uma reivindicação ativa trava a entrada, então ela não pode ser excluída. | 400 |
| EntryBlocked | Uma ordem judicial bloqueia a entrada. | 400 |
### Reivindicações de chave
***
| `code` | Descrição | Status |
| -------------------------------- | ------------------------------------------------------------------------ | ------ |
| ClaimInvalid | Os campos que criam ou atualizam a reivindicação são inválidos. | 400 |
| ClaimTypeInconsistent | O tipo de reivindicação é inconsistente com o estado da entrada. | 400 |
| ClaimKeyNotFound | A chave reivindicada não tem uma entrada registrada. | 404 |
| ClaimAlreadyExistsForKey | Já existe uma reivindicação ativa para a chave. | 400 |
| ClaimResultingEntryAlreadyExists | A entrada resultante já existe para o reivindicante. | 400 |
| ClaimOperationInvalid | O status da reivindicação proíbe a operação solicitada. | 400 |
| ClaimResolutionPeriodNotEnded | O período de resolução ainda não terminou, então a operação é prematura. | 400 |
| ClaimCompletionPeriodNotEnded | O período de conclusão ainda não terminou, então finalizar é prematuro. | 400 |
## Rejeições de arquivo BR Code
***
O canal de arquivo em lote do BR Code responde a uma remessa enviada linha por linha. Uma linha aceita liquida. Uma linha recusada carrega um código de rejeição de três dígitos. Ela também carrega o nome do campo e a descrição que o esquema Pix publica para esse código. Sua conciliação mapeia a resposta contra a própria planilha de erros do esquema.
Duas rejeições recusam uma linha antes que qualquer regra de negócio rode, então são as primeiras que uma nova integração encontra. `063` (Cadastro, Cliente nao cadastrado) diz que o header do arquivo nomeia um recebedor para o qual esse deploy não tem um perfil registrado. `096` (Registro, Inválido) diz que o esquema recusou o registro e não publica um código mais específico para o campo responsável. Um registro de tamanho errado é um desses casos.
Mais quatro cobrem os dois identificadores que a maioria das linhas carrega. `012` (Chave pix, Chave inválida) diz que a linha cobra em uma chave Pix para a qual esse deploy não tem um recebedor registrado. `014` (Chave pix, Não é compatível com o cnpj ou agência e conta informada) nomeia uma chave registrada para outro recebedor. O header do arquivo resolve para um diferente. `016` (Identificador (txid), Em duplicidade) diz que o txid se repete. `017` (Identificador (txid), Inválido ou não encontrado) diz que o movimento nomeia uma cobrança que esse trilho não possui.
A planilha de erros do esquema publica muito mais códigos. O canal renderiza o subconjunto sobre o qual suas próprias recusas mapeiam. Cada linha recusada nomeia seu campo, então leia o nome do campo primeiro e o código depois.