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>.
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

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.	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.

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.

​Códigos do trilho

​400: Requisição inválida

​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

​501: Não implementado

​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

400: Requisição inválida

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

501: Não implementado

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