> ## 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/`. * **`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. 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. Um código pode carregar mais de um status quando a condição que ele nomeia tem mais de uma forma nesse trilho. `SPI-1002` significa que o BACEN recusou a mensagem quando o trilho a enviou. Um pagamento recusado vai para `REJECTED`. O BACEN também pode recusar um pagamento depois, na sua resposta de status (`pacs.002`). Essa recusa não é um erro HTTP, e o pagamento vai para `REJECTED`. Para descobrir quais pagamentos a rede recusou, leia o relatório de pagamentos rejeitados. Ele lista cada um por status e end-to-end id. ### 400: Requisição inválida *** | `code` | Descrição | `detail` | | - | - | - | | SPI-0003 | O corpo da requisição está ausente ou não pode ser interpretado. | request body is required | ### 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 | | SPI-0012 | O CID não tem vínculo de chave ativo no BACEN. | cid has no active binding at bacen | | SPI-0013 | A solicitação de arquivo do conjunto de CIDs não existe para este participante. | cid set file not found | | SPI-1014 | O diretório de chaves Pix não conhece a pessoa em uma requisição de estatísticas. | person not found at bacen dict | | SPI-1015 | O diretório de chaves Pix não possui a chave em uma requisição de estatísticas. | key not found at bacen dict | ### 409: Conflito *** | `code` | Descrição | `detail` | | - | - | - | | SPI-0011 | Já existe um recurso com essa identidade. | participant already exists | | SPI-0014 | O arquivo do conjunto de CIDs ainda não está disponível. | cid set file is not available | | SPI-3006 | O estado atual do ciclo de vida do recurso recusa a operação. | payment is not eligible for return | | SPI-3007 | A requisição conflita com o estado atual do recurso. Outro gravador o alterou, ou uma devolução com a mesma identidade existe ou está em andamento. Leia o recurso novamente antes de tentar de novo. | participant status changed concurrently | | SPI-3008 | A decisão chegou depois da janela regulatória do Pix ou da devolução que ela decide. O próprio trilho fechou a janela, então não tente de novo. | the settlement window for this payment has closed | | SPI-3010 | O participante aguarda o aviso `reda.016` do BACEN, e só esse aviso resolve o status dele. | participant is awaiting the BACEN reda.016 advice; only that advice resolves this status | ### 413: Payload muito grande *** | `code` | Descrição | `detail` | | - | - | - | | SPI-0003 | O corpo da requisição excede o limite de tamanho. `HTTP_BODY_LIMIT_BYTES` define o limite para a maioria das rotas. | request body too large | ### 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-3009 | Uma requisição anterior com esta chave de idempotência pode ter produzido efeito, e o trilho não tem registro do resultado dela. Leia a original antes de enviar de novo. | IDEMPOTENCY\_OUTCOME\_UNRECORDED: an earlier request with this idempotency key may have taken effect and its outcome is not recorded here; check it before sending again | | 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 | ### 501: Não implementado *** | `code` | Descrição | `detail` | | - | - | - | | SPI-1012 | A verificação de chaves em lote do diretório de chaves Pix não está instalada neste deploy. Não tente novamente. | 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 | | SPI-1006 | O BACEN pode ter recebido a mensagem, e o trilho não consegue confirmar isso. Leia o recurso antes de reenviar. | internal error | | SPI-1013 | O diretório de chaves Pix respondeu a uma consulta de chave com uma resposta que o trilho não pode aceitar. | 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 | A mensagem não saiu para o BACEN. Quando o trilho registrou um pagamento Pix ou uma devolução, ele o encerrou como falha: envie um novo para tentar de novo. | 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. Quando o trilho registrou um pagamento Pix ou uma devolução, ele o encerrou como falha. | 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 listam tokens do diretório para registro de chave, consulta de chave, exclusão de chave e as operações de reivindicação. > [!NOTE] > > 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 em um arquivo de retorno. 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. Um arquivo recusado carrega um código, e nenhuma linha dele é julgada. Sua conciliação mapeia a resposta contra a própria planilha de erros do esquema. `063` (Cadastro, Cliente nao cadastrado) recusa o arquivo inteiro: 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 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 txid está malformado ou 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.