Lista de erros do SPI

Formato de erro A API do SPI retorna erros como problem details da RFC 9457, com o media type application/problem+json:

{
  "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/<code>. 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.

​Códigos do trilho

​401: Não autenticado

​403: Proibido

​404: Não encontrado

​409: Conflito

​413: Payload muito grande

​422: Não processável

​429: Muitas requisições

​500: Erro do servidor

​502: Gateway inválido

​503: Serviço indisponível

​504: Timeout do gateway

​Tokens do diretório de chaves Pix

​Geral

​Registro de chave

​Reivindicações de chave

​Rejeições de arquivo BR Code

Códigos do trilho

401: Não autenticado

403: Proibido

404: Não encontrado

409: Conflito

413: Payload muito grande

422: Não processável

429: Muitas requisições

500: Erro do servidor

502: Gateway inválido

503: Serviço indisponível

504: Timeout do gateway

Tokens do diretório de chaves Pix

Geral

Registro de chave

Reivindicações de chave

Rejeições de arquivo BR Code