application/json traz o envelope code, title e message. Uma resposta com o media type application/problem+json traz um problem detail conforme a RFC 9457. Os dois formatos trazem o campo code, então você pode decidir o fluxo com base no valor de PIX-NNNN.
Uma recusa levantada dentro de um handler usa o formato application/problem+json. Uma recusa levantada antes de o handler rodar usa o formato application/json. Um caminho sem correspondência, um método não permitido, um timeout, uma desconexão e a verificação de repetição de idempotência recusam antes de o handler rodar.
{
"code": "PIX-0030",
"title": "Idempotency Key Required",
"message": "The Idempotency-Key header is required for this operation and must be within the accepted length."
}
{
"type": "https://errors.lerian.studio/v1/PIX-0240",
"title": "Not Found",
"status": 404,
"detail": "No collection found for the given identifiers.",
"code": "PIX-0240"
}
application/json traz três campos:
code– Um identificador estável e único do erro (PIX-NNNN). Útil para tratamento programático e para solicitações de suporte.title– Um resumo curto e legível do problema.message– Uma orientação detalhada para ajudar você a resolver o erro.
application/problem+json segue a RFC 9457:
type– Uma URI que identifica o erro no catálogo de erros da Lerian. Montada comohttps://errors.lerian.studio/v1/<code>.title– O texto do status HTTP (por exemplo,Not Found).status– O código de status HTTP.detail– Uma explicação legível para esta ocorrência do problema. Usecodepara decidir o fluxo de forma programática.code– O mesmo identificadorPIX-NNNNque o envelopeapplication/jsontraz.errors– Lista opcional com detalhes de validação por campo, cada um com ummessagee umalocation.instance– Referência de URI opcional que identifica esta ocorrência específica.
Status mostra o status HTTP do código. A coluna detail mostra o texto que o formato application/problem+json traz. No status 500 e acima, esse formato traz o texto fixo internal error, e as tabelas mostram isso nessas linhas.
PIX-0010 e PIX-0000 são códigos genéricos de fallback. Em uma recusa levantada antes de o handler rodar, qualquer um dos dois pode trazer um status diferente do que aparece na tabela.
Erros comuns
O DICT, as cobranças e os pagamentos compartilham estes códigos. Eles vão de
PIX-0000 a PIX-0061.
code | Descrição | Status | detail |
|---|---|---|---|
| PIX-0000 | Erro interno do servidor | 500 | internal error |
| PIX-0001 | Cabeçalhos ausentes na requisição | 400 | Sua requisição está sem um ou mais parâmetros de cabeçalho obrigatórios. |
| PIX-0002 | Campos ausentes na requisição | 400 | Sua requisição está sem um ou mais campos obrigatórios. |
| PIX-0003 | Valores de campo inválidos na requisição | 400 | Sua requisição contém um ou mais campos com um tipo de dado inválido. |
| PIX-0004 | Não autorizado | 401 | Credenciais de autenticação inválidas ou expiradas. |
| PIX-0005 | Proibido | 403 | Você não tem permissão para realizar esta operação. |
| PIX-0006 | Muitas requisições | 429 | Limite de taxa excedido. Aguarde antes de fazer novas requisições. |
| PIX-0008 | Rota não encontrada | 404 | O caminho do recurso solicitado não existe. |
| PIX-0009 | Método não permitido | 405 | O método HTTP não é permitido para este recurso. |
| PIX-0010 | Erro do cliente | 400 | A requisição não pôde ser processada devido a um erro do lado do cliente. |
| PIX-0011 | Entidade não encontrada | 404 | Nenhuma entidade foi encontrada para o ID informado. Confirme que está usando o ID correto. |
| PIX-0012 | Conflito de entidade | 409 | A entidade já existe ou está em conflito com um recurso existente. |
| PIX-0013 | Operação não processável | 422 | A operação não pôde ser processada devido a uma violação de regra de negócio. |
| PIX-0014 | Ação não permitida | 403 | A ação que você está tentando realizar não é permitida no ambiente atual. |
| PIX-0015 | Parâmetro de caminho inválido | 400 | Um ou mais parâmetros de caminho são inválidos. |
| PIX-0016 | Tipo de mídia não suportado | 415 | O corpo da requisição deve ser enviado com Content-Type: application/json. |
| PIX-0017 | Cabeçalhos inválidos na requisição | 400 | Sua requisição contém um ou mais cabeçalhos com um formato inválido. |
| PIX-0018 | Contexto de tenant ausente | 400 | A requisição não pôde ser associada a um tenant. Garanta que a resolução de tenant tenha rodado para esta rota. |
| PIX-0020 | Parâmetro de consulta inválido | 400 | Um ou mais parâmetros de consulta estão em um formato incorreto. |
| PIX-0021 | Formato de data inválido | 400 | Os campos de data estão em um formato incorreto. Use o formato ‘yyyy-mm-dd’. |
| PIX-0022 | Intervalo de datas inválido | 400 | Os campos ‘start_date’ e ‘end_date’ são obrigatórios e devem estar no formato ‘yyyy-mm-dd’. |
| PIX-0023 | Intervalo de datas excede o limite | 400 | O intervalo entre ‘start_date’ e ‘end_date’ excede o limite permitido. |
| PIX-0024 | Limite de paginação excedido | 400 | O limite de paginação excede o número máximo de itens permitidos por página. |
| PIX-0025 | Ordem de classificação inválida | 400 | O campo ‘sort_order’ deve ser ‘asc’ ou ‘desc’. |
| PIX-0026 | Tamanho da chave de metadados excedido | 400 | Uma chave de metadados excede o tamanho máximo permitido. |
| PIX-0027 | Tamanho do valor de metadados excedido | 400 | Um valor de metadados excede o tamanho máximo permitido. |
| PIX-0028 | Aninhamento de metadados inválido | 400 | O objeto de metadados não pode conter valores aninhados. |
| PIX-0030 | Chave de idempotência obrigatória | 400 | O cabeçalho Idempotency-Key é obrigatório para esta operação e deve estar dentro do tamanho aceito. |
| PIX-0031 | Conflito de chave de idempotência | 412 | O Idempotency-Key já foi usado com uma requisição diferente. |
| PIX-0032 | Idempotência indisponível | 503 | internal error |
| PIX-0033 | Efeito de idempotência desconhecido | 409 | Uma tentativa anterior com esta chave de idempotência já foi executada no provedor. A operação deve ser conciliada antes de ser repetida. |
| PIX-0034 | Payload muito grande | 413 | O corpo da requisição excede o tamanho máximo permitido para esta operação. |
| PIX-0050 | Formato do ID de transação inválido | 400 | O ID de transação não corresponde ao formato exigido. |
| PIX-0054 | Timeout do gateway | 504 | internal error |
| PIX-0055 | Cliente desconectado | 499 | O cliente se desconectou antes de a requisição ser concluída. |
| PIX-0061 | Formato de valor inválido | 400 | O valor deve estar em formato decimal com 2 casas decimais. |
Erros do DICT e de chaves Pix
Estes códigos vêm de entradas de chave Pix, consulta de chave, claims, marcadores de fraude, recuperações de fundos e sincronização de chaves. Eles vão de
PIX-0100 a PIX-0174.
code | Descrição | Status | detail |
|---|---|---|---|
| PIX-0100 | Entrada inválida | 422 | Campos obrigatórios ausentes ou malformados. |
| PIX-0101 | Formato de chave inválido | 400 | O valor da chave não corresponde ao formato esperado para este tipo de chave. |
| PIX-0102 | Chave já existe | 409 | O valor da chave já está registrado. |
| PIX-0103 | Limite de chaves excedido | 400 | A conta atingiu o número máximo de chaves para este tipo de chave. |
| PIX-0104 | Falha na verificação de titularidade da conta | 400 | Não foi possível verificar a titularidade da conta via CRM. |
| PIX-0105 | Entrada não encontrada | 404 | A entrada de chave não existe. |
| PIX-0106 | Entrada não ativa | 422 | A entrada de chave não está no status ACTIVE. |
| PIX-0107 | Nenhum campo para atualizar | 400 | Nenhum campo atualizável foi informado. |
| PIX-0108 | Motivo de exclusão obrigatório | 400 | O motivo da exclusão não foi informado. |
| PIX-0109 | Filtro inválido | 400 | Valor de parâmetro de filtro inválido. |
| PIX-0110 | Recuperação de fundos não encontrada | 404 | Não existe recuperação de fundos com o ID informado para este participante. |
| PIX-0111 | Chave de idempotência obrigatória | 400 | O cabeçalho Idempotency-Key é obrigatório para esta operação. |
| PIX-0112 | Conflito de chave de idempotência | 412 | O Idempotency-Key já foi usado com um corpo de requisição diferente. |
| PIX-0113 | Recuperação de fundos já existe | 409 | Já existe uma recuperação de fundos para esta transação raiz. |
| PIX-0114 | Transição de estado de recuperação de fundos inválida | 409 | A operação solicitada não é permitida a partir do status atual da recuperação de fundos. |
| PIX-0115 | Estatísticas de pessoa não encontradas | 404 | Não existe projeção de estatísticas para o identificador fiscal informado. |
| PIX-0116 | Conta não encontrada | 422 | Conta ou titular não encontrado para a chave ou conta informada. |
| PIX-0117 | Prazo de contestação da recuperação de fundos expirado | 422 | O prazo regulatório de contestação desta transação já expirou. |
| PIX-0118 | Resultado da recuperação de fundos pendente | 409 | O provedor aceitou a operação, mas o resultado do BACEN ainda não foi definido; consulte a operação antes de tentar novamente. |
| PIX-0120 | Chave não encontrada | 404 | A chave não existe no diretório do DICT. |
| PIX-0121 | Lista de chaves vazia | 400 | Pelo menos uma chave deve ser informada para a operação de verificação. |
| PIX-0122 | Lista de chaves excede o limite | 400 | O número de chaves excede o máximo permitido (200). |
| PIX-0124 | Chave em custódia | 409 | A chave solicitada já está sob custódia da conta solicitante. |
| PIX-0130 | Marcador de fraude não encontrado | 404 | O marcador de fraude solicitado não foi encontrado no provedor. |
| PIX-0131 | Conflito no marcador de fraude | 409 | A operação de marcador de fraude está em conflito com o estado atual dele no provedor. |
| PIX-0132 | ID de requisição já utilizado | 400 | Este requestId já foi usado com parâmetros diferentes. |
| PIX-0133 | Marcador de fraude proibido | 403 | O solicitante não está autorizado a realizar esta operação de marcador de fraude. |
| PIX-0134 | Marcador de fraude com limite de taxa excedido | 429 | O provedor limitou a taxa desta operação de marcador de fraude. |
| PIX-0140 | CRM indisponível | 502 | internal error |
| PIX-0141 | Falha no adaptador | 502 | internal error |
| PIX-0142 | Campo obrigatório ausente | 400 | Um campo ou cabeçalho obrigatório está ausente na requisição de claim. |
| PIX-0143 | Valor de campo inválido | 400 | Um ou mais campos ou cabeçalhos do claim têm um valor inválido. |
| PIX-0144 | Divergência de repetição do ID de requisição | 409 | O X-Request-Id já foi visto com um corpo de requisição diferente. |
| PIX-0145 | Claim não encontrado | 404 | Nenhum claim foi encontrado para o identificador e a conta informados. |
| PIX-0146 | Configuração de claim não suportada | 422 | A combinação de tipo de claim e tipo de chave solicitada não é suportada. |
| PIX-0147 | Transição de claim inválida | 422 | A transição de estado de claim solicitada não é permitida. |
| PIX-0148 | Limite de taxa de claim excedido | 429 | O limite de taxa para esta operação de claim foi excedido. |
| PIX-0149 | Já existe claim ativo para a chave | 422 | Já existe um claim ativo para esta chave. |
| PIX-0150 | Orçamento diário esgotado | 429 | O orçamento diário de requisições está esgotado para createCidSetFile. |
| PIX-0151 | Estado de VSync não encontrado | 404 | Não existe estado de VSync para o escopo solicitado. |
| PIX-0152 | Job de conciliação não encontrado | 404 | O job de conciliação não existe. |
| PIX-0153 | Discrepância não encontrada | 404 | O registro de discrepância não existe. |
| PIX-0154 | Discrepância já resolvida | 409 | A discrepância já foi resolvida. |
| PIX-0155 | Job não pode ser repetido | 409 | O job de conciliação não está em um estado que permite nova tentativa. |
| PIX-0156 | Já existe job ativo | 409 | Já existe um job de conciliação ativo para este escopo. |
| PIX-0157 | Escopo inválido | 400 | ISPB ou tipo de chave desconhecido no escopo solicitado. |
| PIX-0158 | Orçamento de verificação esgotado | 429 | O orçamento de requisições está esgotado para verificações de sincronização. |
| PIX-0159 | Escopo não está bloqueado para escalonamento | 409 | O escopo solicitado não está no status ESCALATION_BLOCKED. |
| PIX-0160 | Log de conciliação não encontrado | 404 | A entrada de log de conciliação não existe. |
| PIX-0161 | Job de webhook não encontrado | 404 | Nenhum job de conciliação foi encontrado para o escopo informado. |
| PIX-0162 | Payload de webhook inválido | 400 | O payload do webhook é inválido ou contém dados inconsistentes. |
| PIX-0163 | Claim bloqueado por fraude | 422 | O claim foi rejeitado porque a chave está marcada para fraude. |
| PIX-0164 | Adaptador de claim indisponível | 503 | internal error |
| PIX-0165 | Claim não pode ser confirmado | 422 | As pré-condições de confirmação não são atendidas para este claim. |
| PIX-0166 | Mesmo participante | 422 | Os participantes doador e solicitante do claim devem ser diferentes. |
| PIX-0167 | Período de resolução ausente | 422 | O período de resolução é obrigatório para esta transição de claim. |
| PIX-0168 | Estado terminal | 422 | O claim está em um estado terminal e não pode ser alterado. |
| PIX-0169 | Alterações de claim temporariamente bloqueadas | 503 | internal error |
| PIX-0171 | Chave não existe | 422 | A chave não está registrada no diretório; não há nada para reivindicar. |
| PIX-0172 | Data de abertura inválida | 422 | A data de abertura da conta retornada pelo CRM não pôde ser processada. |
| PIX-0173 | Chave já pertence ao titular | 422 | A chave já pertence ao titular solicitante. |
| PIX-0174 | Escopo de verify-sync inválido | 422 | ISPB ou tipo de chave desconhecido no escopo de verify-sync solicitado. |
Erros de cobranças e BR Code
Estes códigos vêm de BR Codes, cobranças imediatas e cobranças com vencimento. Eles vão de
PIX-0200 a PIX-0267.
code | Descrição | Status | detail |
|---|---|---|---|
| PIX-0200 | Entrada inválida | 400 | Campos obrigatórios ausentes ou malformados. |
| PIX-0201 | Chave não encontrada | 422 | A chave Pix não existe ou não está ativa. |
| PIX-0202 | Nome do lojista muito longo | 400 | O nome do lojista excede o limite EMV de 25 caracteres. |
| PIX-0203 | Cidade do lojista muito longa | 400 | A cidade do lojista excede o limite EMV de 15 caracteres. |
| PIX-0204 | Falha na geração EMV | 500 | internal error |
| PIX-0205 | BR Code não encontrado | 404 | O BR Code não existe para esta organização. |
| PIX-0206 | Filtro inválido | 400 | Valor de parâmetro de filtro inválido. |
| PIX-0207 | Campo do BR Code excede o tamanho para codificação | 422 | keyValue e description juntos excedem o tamanho que o template de lojista do BR Code consegue codificar. Reduza a description ou use uma chave Pix mais curta. |
| PIX-0220 | Payload EMV malformado | 400 | O payload EMV está malformado ou não é um QR code Pix válido. |
| PIX-0221 | Falha ao decodificar QR code | 400 | Não foi possível processar o QR code. |
| PIX-0222 | Falha na resolução de QR dinâmico | 502 | internal error |
| PIX-0223 | Adaptador inacessível | 502 | internal error |
| PIX-0224 | Provedor rejeitou a cobrança | 400 | O provedor rejeitou a requisição de cobrança. |
| PIX-0225 | Recurso do provedor não encontrado | 404 | O recurso de cobrança solicitado não foi encontrado no provedor. |
| PIX-0226 | Conflito de estado no provedor | 409 | A cobrança está em um estado conflitante no provedor. |
| PIX-0240 | Cobrança não encontrada | 404 | Nenhuma cobrança encontrada para os identificadores informados. |
| PIX-0241 | Cobrança em estado terminal | 422 | A cobrança está em um estado terminal (já CANCELLED ou COMPLETED) e não pode fazer a transição. |
| PIX-0242 | Cobrança já paga | 409 | A cobrança já foi marcada como paga. |
| PIX-0260 | Data de vencimento obrigatória | 400 | O calendário de vencimento (dueDate/validityAfterDue) é obrigatório para uma cobrança com vencimento. |
| PIX-0261 | Validade após vencimento inválida | 400 | validityAfterDue deve ser zero ou um número positivo de dias corridos. |
| PIX-0262 | Devedor obrigatório | 400 | O bloco de devedor é obrigatório para uma cobrança com vencimento. |
| PIX-0263 | Termos de multa inválidos | 400 | A modalidade ou o valor da multa são inválidos. |
| PIX-0264 | Termos de juros inválidos | 400 | A modalidade ou o valor dos juros são inválidos. |
| PIX-0265 | Termos de abatimento inválidos | 400 | A modalidade ou o valor do abatimento são inválidos. |
| PIX-0266 | Termos de desconto inválidos | 400 | A modalidade, o valor ou as datas fixas do desconto são inválidos. |
| PIX-0267 | Data de vencimento inválida | 400 | dueDate não pode ser anterior a hoje. |
Erros de pagamentos e devoluções
Estes códigos vêm de transferências Pix, devoluções e a liquidação delas. Eles vão de
PIX-0300 a PIX-0706.
code | Descrição | Status | detail |
|---|---|---|---|
| PIX-0300 | Campos ausentes ou malformados | 400 | Campos obrigatórios ausentes ou malformados para a iniciação da transferência. |
| PIX-0301 | Divergência no tipo de iniciação | 400 | initiationType não corresponde aos campos de destino informados. |
| PIX-0302 | Conta de origem inválida | 400 | Conta de origem não encontrada ou inativa no CRM. |
| PIX-0303 | Chave DICT não encontrada | 422 | A consulta à chave DICT não retornou resultados. |
| PIX-0304 | Falha ao decodificar QR code | 422 | Não foi possível decodificar o QR code. |
| PIX-0320 | Iniciação não encontrada | 404 | O ID de iniciação não existe. |
| PIX-0321 | Iniciação expirada | 422 | A iniciação expirou. |
| PIX-0322 | Iniciação já confirmada | 409 | A iniciação já foi confirmada. |
| PIX-0323 | Falha no débito do Midaz | 422 | O débito no Midaz falhou por saldo insuficiente. |
| PIX-0324 | Falha na transação do Midaz | 502 | internal error |
| PIX-0325 | Falha na chamada ao provedor após o débito | 502 | internal error |
| PIX-0326 | Iniciação cancelada | 409 | A iniciação foi cancelada e não pode ser processada. |
| PIX-0327 | Conflito na transferência | 409 | A transferência mudou durante esta requisição. Repita a operação. |
| PIX-0328 | Conta do ledger bloqueada | 422 | A conta do ledger está bloqueada e não pode ser usada para a operação solicitada. |
| PIX-0329 | Saldo do ledger não encontrado | 422 | Não existe registro de saldo para a conta e o ativo informados. |
| PIX-0340 | Transferência não encontrada | 404 | O ID de transferência não existe para esta organização. |
| PIX-0341 | Parâmetro de filtro inválido | 400 | Valor de parâmetro de filtro inválido. |
| PIX-0342 | Intervalo de datas excede o limite | 400 | O intervalo de datas excede 90 dias. |
| PIX-0400 | Transferência original não encontrada | 404 | A transferência original não existe. |
| PIX-0401 | Transferência não concluída | 422 | A transferência original não está no status COMPLETED. |
| PIX-0402 | Valor da devolução excede o restante | 422 | O valor da devolução excede o valor restante disponível para devolução. |
| PIX-0403 | Campos ausentes ou malformados | 400 | Campos obrigatórios ausentes ou malformados para a devolução. |
| PIX-0404 | Falha na chamada ao provedor | 502 | internal error |
| PIX-0405 | Falha na transação do Midaz | 502 | internal error |
| PIX-0406 | Conflito na devolução | 409 | A devolução mudou durante esta requisição. Repita a operação. |
| PIX-0420 | Devolução não encontrada | 404 | O ID de devolução não existe para esta organização. |
| PIX-0421 | Parâmetro de filtro inválido | 400 | Valor de parâmetro de filtro inválido. |
| PIX-0422 | Intervalo de datas excede o limite | 400 | O intervalo de datas excede 90 dias. |
| PIX-0450 | Conta de destino não encontrada | 422 | A conta de destino não existe. |
| PIX-0451 | Conta de destino não ativa | 422 | A conta de destino não está ativa. |
| PIX-0453 | CRM indisponível | 502 | internal error |
| PIX-0454 | Midaz indisponível | 502 | internal error |
| PIX-0470 | Pagamento não encontrado | 404 | Nenhum pagamento aprovado para este endToEndId. |
| PIX-0472 | Falha no crédito do Midaz | 502 | internal error |
| PIX-0500 | Transferência original não encontrada | 404 | Transferência original não encontrada para este endToEndId. |
| PIX-0501 | Devolução excede o restante | 422 | A devolução excede o valor restante disponível para devolução. |
| PIX-0502 | Campos ausentes ou malformados | 400 | Campos obrigatórios ausentes ou malformados. |
| PIX-0520 | Devolução não encontrada | 404 | Nenhuma devolução aprovada para este endToEndId. |
| PIX-0521 | Já liquidada | 409 | A devolução já foi liquidada. |
| PIX-0522 | Falha no crédito do Midaz | 502 | internal error |
| PIX-0550 | Entidade não encontrada | 404 | Nenhuma entidade em PROCESSING encontrada para este endToEndId. |
| PIX-0551 | Estado inesperado | 409 | Callback recebido para uma entidade que não está no estado PROCESSING. |
| PIX-0552 | Status inválido | 400 | O status não é um estado terminal válido. |
| PIX-0553 | Falha ao reverter no Midaz | 502 | internal error |
| PIX-0554 | Entidade já terminal | 409 | A entidade já atingiu um estado terminal; não há nada para desbloquear. |
| PIX-0555 | Tempo de processamento insuficiente | 409 | A entidade não está em PROCESSING há tempo suficiente para ser desbloqueada; aguarde e tente novamente. |
| PIX-0556 | Provedor ainda sem resultado terminal | 409 | O provedor ainda não chegou a um resultado terminal para esta entidade; aguarde e tente novamente. |
| PIX-0557 | Provedor inacessível | 502 | internal error |
| PIX-0650 | Conta de bloqueio não configurada | 422 | A conta de bloqueio não está configurada para este participante. |
| PIX-0652 | Falha no ledger | 502 | internal error |
| PIX-0653 | Liquidação em andamento | 409 | O bloqueio está sendo liquidado e não pode ser cancelado ou reiniciado; confirme ou encerre-o. |
| PIX-0654 | Nada a liquidar | 422 | Não há nada restante a liquidar para este bloqueio. |
| PIX-0655 | Alias de conta não resolvível | 422 | Uma conta necessária para esta operação não tem alias resolvível no ledger. |
| PIX-0700 | Hub do DICT indisponível | 502 | internal error |
| PIX-0701 | Hub do COB indisponível | 502 | internal error |
| PIX-0702 | CRM indisponível | 502 | internal error |
| PIX-0703 | Recurso não encontrado | 404 | O recurso do SPI solicitado não foi encontrado. |
| PIX-0704 | Conflito de estado | 409 | O recurso está em um estado conflitante para a operação solicitada. |
| PIX-0705 | Serviço upstream indisponível | 502 | internal error |
| PIX-0706 | Requisição inválida | 400 | A requisição é inválida. |