> ## 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 Pix JD
> Consulte um código PIX-NNNN no catálogo do Pix JD, a condição por trás dele e o texto detail que a resposta traz.
**Formato de erro**
A API do Pix JD responde a uma requisição que falhou com `application/problem+json`. O esquema `Detail` desta referência de API descreve esse corpo, que segue a RFC 9457.
```json JSON theme={null}
{
"type": "https://errors.lerian.studio/v1/PIX-0012",
"title": "PIX Key Not Found",
"status": 404,
"detail": "The specified PIX key was not found in the system. Please verify the key value and try again.",
"code": "PIX-0012"
}
```
**Definições de campo**
* **`code`** – Código de erro de domínio estável e legível por máquina, limitado ao serviço que o emite. Nesta API, ele tem a forma `PIX-NNNN`.
* **`title`** – Um resumo curto e legível do tipo de problema. Recomenda-se que esse valor não mude entre ocorrências do erro.
* **`detail`** – Uma explicação legível específica para esta ocorrência do problema.
* **`status`** – O código de status HTTP.
* **`type`** – Um URI que identifica o erro no catálogo de erros da Lerian, construído como `https://errors.lerian.studio/v1/`.
* **`instance`** – Uma referência de URI que identifica a ocorrência específica do problema.
* **`errors`** – Uma lista opcional de detalhes por campo. Cada entrada traz o `location` que falhou, uma `message` e o `value` daquele local.
* **`upstream`** – Um membro de extensão da RFC 9457. Ele traz o código e a mensagem relatados por um provedor terceiro por trás de um proxy, e fica ausente a menos que o serviço tenha exposto um.
**Como ler estas tabelas**
Cada linha começa com o status HTTP que a resposta carrega. Em seguida, nomeia a condição. A última coluna traz o texto `detail` que o serviço envia por padrão. Quando o serviço monta esse texto a partir da requisição que falhou, a linha indica isso.
A partir do status 500, a resposta carrega texto fixo, não a causa bruta. A coluna `detail` mostra se um código envia `internal error` ou uma frase que o serviço escreveu para ele.
## Requisições e regras de negócio do serviço Pix
***
Esses códigos vêm do próprio serviço Pix. Eles cobrem validação de requisição, gestão de chaves Pix, reivindicação de chaves, ordens de pagamento, devoluções, QR codes, participantes indiretos e créditos recebidos.
### Validação de requisição e acesso
| `code` | Descrição | `detail` |
| ---------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `PIX-0001` | **400** Erro de validação de campo | Um ou mais campos contêm erros de validação. Verifique o objeto de campos para obter detalhes e corrija os valores inválidos. |
| `PIX-0002` | **400** Requisição inválida | Definido pela operação que gerou o erro. |
| `PIX-0003` | **400** Campos inesperados | Definido pela operação que gerou o erro. |
| `PIX-0004` | **401** Não autorizado | Definido pela operação que gerou o erro. |
| `PIX-0005` | **403** Proibido | Definido pela operação que gerou o erro. |
| `PIX-0006` | **404** Não encontrado | Definido pela operação que gerou o erro. |
| `PIX-0007` | **409** Conflito | Definido pela operação que gerou o erro. |
| `PIX-0008` | **422** Entidade não processável | Definido pela operação que gerou o erro. |
| `PIX-0009` | **429** Muitas requisições | Definido pela operação que gerou o erro. |
| `PIX-0019` | **400** Tipo de conta inválido | O tipo de conta é inválido para esta operação. Verifique o tipo de conta e tente novamente. |
| `PIX-0058` | **400** ID inválido | O ID fornecido é inválido ou malformado. Verifique o formato do ID e tente novamente. |
| `PIX-0059` | **401** Token inválido | O token fornecido é inválido ou expirou. Obtenha um novo token e tente novamente. |
| `PIX-0060` | **400** Localização obrigatória | Informações de localização são obrigatórias para esta operação. Forneça dados de localização válidos. |
| `PIX-0061` | **400** Parâmetros inválidos | Um ou mais parâmetros da requisição são inválidos. Verifique os valores dos parâmetros e tente novamente. |
| `PIX-0062` | **400** Informação inválida | A informação fornecida é inválida ou está incompleta. Verifique todos os campos e tente novamente. |
| `PIX-0082` | **401** Autenticação obrigatória | Credenciais de autenticação válidas são obrigatórias para acessar este recurso. Forneça um bearer token válido. |
| `PIX-0083` | **403** Acesso proibido | Você não tem permissões suficientes para realizar esta ação. Entre em contato com o suporte se você acredita que isso é um erro. |
| `PIX-0084` | **400** Erro de validação da requisição | A validação da requisição falhou. Verifique todos os campos obrigatórios e tente novamente. |
### Chaves Pix
| `code` | Descrição | `detail` |
| ---------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `PIX-0010` | **422** Formato de chave Pix inválido | O formato da chave PIX é inválido para o tipo especificado. Verifique se o formato corresponde ao padrão esperado e tente novamente. |
| `PIX-0011` | **409** Chave Pix já existe | Já existe uma chave PIX com este valor. Use uma chave PIX diferente. |
| `PIX-0012` | **404** Chave Pix não encontrada | A chave PIX especificada não foi encontrada no sistema. Verifique o valor da chave e tente novamente. |
| `PIX-0013` | **429** Limite de chaves Pix excedido | Você atingiu o número máximo de chaves PIX permitido. Exclua uma chave existente antes de criar uma nova. |
| `PIX-0014` | **422** Tipo de chave Pix inválido | O tipo de chave PIX não é válido para esta operação. Use um tipo de chave aceito. |
| `PIX-0015` | **422** Chave Pix expirada | Definido pela operação que gerou o erro. |
| `PIX-0016` | **422** Chave Pix pendente de confirmação | Definido pela operação que gerou o erro. |
| `PIX-0017` | **422** Chave Pix inativa | Definido pela operação que gerou o erro. |
| `PIX-0018` | **403** Exclusão de chave Pix não permitida | Esta chave PIX não está registrada na conta informada, portanto não pode ser excluída. Verifique a chave e a conta. |
| `PIX-0067` | **422** Chave Pix expirada | A chave PIX expirou e não pode ser usada. Crie uma nova chave PIX. |
| `PIX-0068` | **422** Confirmação de chave Pix obrigatória | A chave PIX exige confirmação antes da ativação. Verifique seu e-mail ou SMS em busca do código de confirmação. |
| `PIX-0069` | **404** Chave Pix não encontrada | A chave PIX especificada não foi encontrada no sistema. Verifique o valor da chave e tente novamente. |
| `PIX-0070` | **422** Chave Pix inválida | A chave PIX é inválida ou foi desativada. Use uma chave PIX válida. |
| `PIX-0071` | **409** Chave Pix já possuída | Você já possui esta chave PIX. Cada chave PIX pode ser associada a apenas uma conta. |
| `PIX-0072` | **422** Limite de chaves Pix excedido | Você atingiu o número máximo de chaves PIX permitido. Exclua uma chave existente antes de criar uma nova. |
| `PIX-0073` | **422** Status de chave Pix inválido | A chave PIX não está em um status válido para esta operação. Verifique o status da chave. |
| `PIX-0074` | **404** Chave Pix interna não encontrada | A referência interna da chave PIX não foi encontrada. Entre em contato com o suporte. |
| `PIX-0086` | **422** Divergência de documento | O documento da conta não corresponde ao documento associado à chave PIX. Apenas o dono da chave pode reivindicá-la. |
### Reivindicações de chave Pix
| `code` | Descrição | `detail` |
| ---------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `PIX-0020` | **404** Reivindicação não encontrada | A reivindicação especificada não foi encontrada para esta conta. Verifique o ID da reivindicação e tente novamente. |
| `PIX-0021` | **409** Reivindicação já existe | Definido pela operação que gerou o erro. |
| `PIX-0022` | **422** Reivindicação de chave Pix ou instrução agendada está em um status que esta ação não permite | A autorização do Pix Automático não está em um status válido para esta operação. Verifique o status da autorização. |
| `PIX-0023` | **422** Reivindicação expirada | Definido pela operação que gerou o erro. |
| `PIX-0024` | **403** Ação não autorizada na reivindicação | Definido pela operação que gerou o erro. |
| `PIX-0025` | **409** Reivindicação já processada | Definido pela operação que gerou o erro. |
| `PIX-0026` | **422** Dados de reivindicação inválidos | Definido pela operação que gerou o erro. |
| `PIX-0027` | **400** Reivindicação indica um participante que não corresponde ao registro da chave | Definido pela operação que gerou o erro. |
### Transações e pagamentos
| `code` | Descrição | `detail` |
| ---------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `PIX-0028` | **404** Transação não encontrada | Definido pela operação que gerou o erro. |
| `PIX-0029` | **409** Transação duplicada | Já existe uma transação com este identificador. Use um ID de transação exclusivo. |
| `PIX-0030` | **422** Valor de transação inválido | O valor da transação é inválido. Forneça um valor positivo válido. |
| `PIX-0031` | **400** Saldo insuficiente | Definido pela operação que gerou o erro. |
| `PIX-0032` | **409** Limite de transação excedido | Definido pela operação que gerou o erro. |
| `PIX-0033` | **422** Dados do destinatário inválidos | Os dados do destinatário são inválidos. Verifique todas as informações do destinatário. |
| `PIX-0034` | **422** Transação expirada | Definido pela operação que gerou o erro. |
| `PIX-0035` | **422** Transação cancelada | Definido pela operação que gerou o erro. |
| `PIX-0036` | **422** Status de transação inválido | A transição de status da transação não é permitida para o estado atual. |
| `PIX-0037` | **422** ID end-to-end inválido | O id end-to-end é inválido para esta ordem de pagamento. Verifique o valor e tente novamente. |
| `PIX-0075` | **409** Limite de transação excedido | O valor da transação excede seus limites configurados. Tente um valor menor ou entre em contato com o suporte para aumentar seus limites. |
| `PIX-0076` | **409** Saldo insuficiente | Sua conta não tem saldo suficiente para esta transação. Adicione fundos à sua conta e tente novamente. |
| `PIX-0077` | **409** Transferência para o mesmo Bank ID não permitida | Transferências para o mesmo Bank ID não são permitidas para esta operação. Use um destino diferente. |
| `PIX-0078` | **409** Transferência para a mesma conta não permitida | Transferências para a mesma conta não são permitidas. Use uma conta de destino diferente. |
| `PIX-0090` | **422** Saldo insuficiente para bloqueio | A conta transacional do pagador não tem saldo suficiente para reservar o débito agendado. (SGCTPIX001) |
| `PIX-0091` | **500** Bloqueio rejeitado | `internal error` |
### Devoluções e reembolsos
| `code` | Descrição | `detail` |
| ---------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `PIX-0038` | **403** Devolução não permitida | Definido pela operação que gerou o erro. |
| `PIX-0039` | **422** Motivo de devolução inválido | Definido pela operação que gerou o erro. |
| `PIX-0040` | **422** Valor da devolução excede o original | Definido pela operação que gerou o erro. |
| `PIX-0041` | **403** Prazo de devolução expirado | Definido pela operação que gerou o erro. |
| `PIX-0042` | **404** Transação original não encontrada | Definido pela operação que gerou o erro. |
| `PIX-0087` | **400** Não é possível reembolsar a própria transação | Você não pode solicitar reembolso da sua própria transação de saída. Apenas o destinatário pode solicitar um reembolso. |
| `PIX-0088` | **400** Não é possível reembolsar transação não recebida | Você pode solicitar reembolso apenas de transações que recebeu. |
| `PIX-0089` | **400** Não é possível reembolsar transação de saída | Transações de saída (CASH\_OUT) não podem ser reembolsadas. Apenas transações recebidas podem ser reembolsadas. |
### Participantes e contas
| `code` | Descrição | `detail` |
| ---------- | -------------------------------- | ---------------------------------------- |
| `PIX-0043` | **422** Bank ID inválido | Definido pela operação que gerou o erro. |
| `PIX-0044` | **422** Bank ID não participante | Definido pela operação que gerou o erro. |
| `PIX-0045` | **422** Número de conta inválido | Definido pela operação que gerou o erro. |
| `PIX-0046` | **422** Conta bloqueada | Definido pela operação que gerou o erro. |
| `PIX-0047` | **422** Conta encerrada | Definido pela operação que gerou o erro. |
### QR codes
| `code` | Descrição | `detail` |
| ---------- | ---------------------------- | ---------------------------------------- |
| `PIX-0048` | **422** QR code inválido | Definido pela operação que gerou o erro. |
| `PIX-0049` | **504** QR code expirado | `internal error` |
| `PIX-0050` | **422** QR code já utilizado | Definido pela operação que gerou o erro. |
### Entidades, templates e conciliação
| `code` | Descrição | `detail` |
| ---------- | ----------------------------------- | --------------------------------------------------------------------------------------------------- |
| `PIX-0063` | **404** Entidade não encontrada | A entidade especificada não foi encontrada no sistema. Verifique o identificador e tente novamente. |
| `PIX-0064` | **409** Entidade já existe | Já existe uma entidade com este identificador. Use um identificador exclusivo. |
| `PIX-0065` | **409** ID de conciliação já existe | Já existe um registro com este ID de conciliação. Use um ID de conciliação exclusivo. |
| `PIX-0066` | **404** Template não encontrado | O template especificado não foi encontrado. Verifique o identificador do template. |
| `PIX-0110` | **409** Entidade já retirada | A entidade especificada já foi retirada e não pode mais receber ações. |
### Fraude, conformidade e regulação
| `code` | Descrição | `detail` |
| ---------- | -------------------------------- | ---------------------------------------- |
| `PIX-0055` | **400** Fraude detectada | Definido pela operação que gerou o erro. |
| `PIX-0056` | **403** Violação de conformidade | Definido pela operação que gerou o erro. |
| `PIX-0057` | **403** Restrição regulatória | Definido pela operação que gerou o erro. |
### Falhas de serviço e dependência
| `code` | Descrição | `detail` |
| ---------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `PIX-0051` | **503** Serviço indisponível | A integração PIX está temporariamente indisponível para este tenant. Tente novamente em instantes. |
| `PIX-0052` | **504** Timeout | `internal error` |
| `PIX-0053` | **500** Erro interno | `internal error` |
| `PIX-0054` | **502** Erro de serviço externo | `internal error` |
| `PIX-0079` | **502** Erro de serviço externo | `internal error` |
| `PIX-0080` | **500** Erro de core banking | `internal error` |
| `PIX-0085` | **500** Erro de conexão com o banco de dados | `internal error` |
| `PIX-0109` | **500** Falha do servidor que o serviço não conseguiu atribuir a uma condição específica | `internal error` |
### Configuração do tenant
| `code` | Descrição | `detail` |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PIX-0092` | **409** Integração Pix do tenant não provisionada | A integração PIX para este tenant não foi provisionada. Entre em contato com o suporte para concluir o onboarding do tenant. |
| `PIX-0105` | **409** Configuração de rota do tenant ausente | A configuração de roteamento PIX para este tenant está ausente ou é inválida. Entre em contato com o suporte para concluir o onboarding do tenant. |
| `PIX-0106` | **409** Configuração de ledger do tenant ausente | A identidade de ledger do Midaz para este tenant não está provisionada, então nenhuma transação foi lançada. Tanto o ativo de lançamento quanto a conta externa de compensação devem estar definidos: no modo multi-tenant, as chaves do systemplane tenant\_policy/midaz.asset\_id e tenant\_policy/midaz.external\_id; no modo single-tenant, os valores de deployment MIDAZ\_ASSET\_ID e MIDAZ\_EXTERNAL\_ID. Apenas um operador pode fornecê-los, então repetir esta requisição sem essa mudança falhará de forma idêntica. |
| `PIX-0107` | **409** Criptografia de entrega indireta não provisionada. Gerado quando a chave de criptografia do segredo de entrega do tenant está ausente, em branco ou malformada, e quando nenhuma cifra está conectada. Ausente e malformada compartilham este código porque compartilham a correção: um operador altera o valor. No single-tenant, esse valor é `INDIRECTS_DELIVERY_ENCRYPTION_KEY`, e deve ter exatamente 64 caracteres hexadecimais (uma chave AES-256 codificada em hexadecimal) | Nenhuma chave de criptografia do segredo de entrega está provisionada para este tenant, então o participante indireto não foi salvo e nenhum segredo foi armazenado. Deployments single-tenant definem INDIRECTS\_DELIVERY\_ENCRYPTION\_KEY; deployments multi-tenant provisionam a chave de criptografia do segredo de entrega deste tenant no secret store do deployment. Apenas um operador pode fornecê-la, então repetir esta requisição sem essa mudança falhará de forma idêntica. |
| `PIX-0108` | **422** Alias de conta do ledger não resolvido | Definido pela operação que gerou o erro. |
| `PIX-0121` | **409** ISPB da integração Pix do tenant inválido | A integração PIX deste tenant está configurada incorretamente: o campo "ispb" da chave systemplane tenancy/jd\_integration\_binding deve ter exatamente 8 dígitos. Entre em contato com o suporte para corrigir o binding de integração PIX do tenant. |
| `PIX-0122` | **503** Configuração de ledger do tenant ilegível | A identidade de ledger do Midaz para este tenant não pôde ser lida a partir do plano de configuração do tenant, então nenhuma transação foi lançada. Não se sabe se a configuração está ausente: a leitura em si não foi concluída. Portanto, esta é uma falha do nosso lado, não uma lacuna de onboarding. Tente novamente em instantes; se persistir, entre em contato com o suporte. |
| `PIX-0123` | **503** Fonte da chave de entrega indireta indisponível | A chave de criptografia do segredo de entrega para este tenant não pôde ser lida da sua fonte, então o participante indireto não foi salvo e nenhum segredo foi armazenado. Não se sabe se a chave está ausente: a leitura em si não foi concluída. Portanto, esta é uma falha do nosso lado, não uma lacuna de onboarding. Tente novamente em instantes; se persistir, entre em contato com o suporte. |
**Se vale a pena tentar de novo é decidido pelo status, não pela família.** Um `409` nesta seção é uma lacuna de provisionamento: sabe-se que o valor está ausente, apenas um operador pode fornecê-lo, e repetir a requisição não pode mudar isso. Um `503` é o irmão *ilegível* da mesma condição: **não** se sabe se a configuração está ausente, a leitura em si não foi concluída. Por isso, ele nomeia a dependência com falha e vale a pena tentar de novo.
Os pares são `PIX-0092`/`PIX-0121` contra `PIX-0051`, `PIX-0106` contra `PIX-0122`, e `PIX-0107` contra `PIX-0123`.
### Participantes indiretos
| `code` | Descrição | `detail` |
| ---------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PIX-0093` | **409** Conflito de ISPB indireto | Um participante indireto com este ISPB já está registrado e ativo para este tenant. Um indireto encerrado pode ser registrado novamente, mas um aberto é único por ISPB. |
| `PIX-0094` | **409** Transição indireta ilegal | A mudança de ciclo de vida solicitada não é permitida para o status atual do participante indireto. |
| `PIX-0095` | **404** Indireto não encontrado | O participante indireto especificado não foi encontrado para este tenant. Verifique o identificador e tente novamente. |
| `PIX-0096` | **409** Não é possível encerrar indireto com saldo | O participante indireto não pode ser encerrado enquanto sua conta PIX mantiver fundos. Zere o saldo disponível e o valor retido e tente novamente. |
| `PIX-0097` | **409** Indireto não aguarda provisionamento | A nova tentativa de provisionamento apenas é válida para um participante indireto no estado PENDING\_PROVISIONING. |
| `PIX-0098` | **422** Participante indireto inválido | A requisição do participante indireto é inválida. Verifique o nome, o ISPB, o endpoint de entrega, o secret e o modo de mensageria, e tente novamente. |
| `PIX-0099` | **502** Provisionamento indireto falhou | `internal error` |
| `PIX-0100` | **422** Indireto não ativo | O participante indireto especificado não está ativo e não pode originar uma transação. Reative-o e tente novamente. |
| `PIX-0102` | **422** Divergência de pagador indireto | O ISPB do pagador fornecido não corresponde ao participante indireto resolvido. Verifique o identificador indireto e os dados do pagador, e tente novamente. |
| `PIX-0103` | **409** Retenção de crédito não está aberta | O crédito recebido retido não está mais como PARKED (já foi resolvido ou rejeitado, possivelmente por uma requisição concorrente). Nenhuma ação adicional foi realizada. |
| `PIX-0104` | **409** Alvo indireto não ativo | O participante indireto alvo desta resolução não está ACTIVE e não pode receber o crédito. Reative-o ou escolha um alvo diferente. |
| `PIX-0111` | **422** Recurso de indiretos desabilitado | Definido pela operação que gerou o erro. |
| `PIX-0112` | **422** Localização do QR indireto muito longa | Definido pela operação que gerou o erro. |
| `PIX-0113` | **422** Host do QR indireto não é público | Definido pela operação que gerou o erro. |
| `PIX-0114` | **422** Indireto não tem certificado QR próprio | Definido pela operação que gerou o erro. |
### Créditos recebidos
| `code` | Descrição | `detail` |
| ---------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PIX-0115` | **404** Conta de cash-in não encontrada | A conta recebedora indicada por este crédito não foi encontrada neste participante, portanto nenhum crédito foi registrado. |
| `PIX-0116` | **409** Destino do cash-in ambíguo | O documento do recebedor indica mais de uma conta neste participante, então não é possível determinar o destino deste crédito. Nenhum crédito foi registrado. Direcione o crédito para uma conta específica (recebedor.nrAgencia e recebedor.nrConta) ou entre em contato com este participante para corrigir os registros duplicados. |
| `PIX-0117` | **409** Divergência de titular do cash-in | A conta endereçada por este crédito pertence a um titular diferente do indicado pelo documento do recebedor, então nenhum crédito foi registrado. Verifique recebedor.cpfCnpj em relação a recebedor.nrAgencia e recebedor.nrConta. |
| `PIX-0118` | **409** Conta de cash-in não creditável | A conta endereçada por este crédito existe neste participante, mas não está configurada para receber créditos, então nenhum crédito foi registrado. Entre em contato com este participante para que o registro da conta seja completado. |
| `PIX-0119` | **404** Recebedor do cash-in não atendido | O participante recebedor indicado por este crédito não é atendido por este participante, então nenhum crédito foi registrado. Verifique recebedor.ispb. |
| `PIX-0120` | **500** Ledger de cash-in mal provisionado | `internal error` |
## Trilho Pix e diretório de chaves
***
Esses códigos vêm da infraestrutura Pix conectada. O serviço traduz uma falha do trilho em um destes códigos antes de responder. Quem chama a API decide o fluxo com base no valor `PIX-NNNN`, não no vocabulário próprio do trilho.
### Validação de requisição e autenticação
| `code` | Descrição | `detail` |
| ---------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `PIX-1000` | **400** Erro de validação de campo | Um ou mais campos contêm erros de validação. Verifique o objeto de campos para obter detalhes e corrija os valores inválidos. |
| `PIX-1001` | **400** Requisição inválida | O servidor não conseguiu entender a requisição devido a sintaxe malformada. Verifique o formato da requisição e tente novamente. |
| `PIX-1002` | **400** Campos inesperados na requisição | O corpo da requisição contém mais campos do que o esperado. Envie apenas os campos permitidos conforme a documentação. |
| `PIX-1003` | **401** Não autorizado | As credenciais de autenticação estavam ausentes ou incorretas. Forneça credenciais válidas. |
| `PIX-1004` | **403** Proibido | O servidor entendeu a requisição, mas se recusa a autorizá-la. Verifique suas permissões. |
| `PIX-1005` | **404** Não encontrado | O recurso solicitado não foi encontrado. Verifique o identificador e tente novamente. |
| `PIX-1006` | **409** Conflito | A requisição não pôde ser concluída devido a um conflito com o estado atual. |
| `PIX-1007` | **422** Entidade não processável | A requisição estava bem formada, mas não pôde ser processada devido a erros semânticos. |
| `PIX-1008` | **429** Muitas requisições | Muitas requisições foram enviadas. Aguarde antes de fazer outra requisição. |
| `PIX-1059` | **400** Token de autenticação ausente | O token de autenticação está ausente na requisição. Forneça um Bearer token válido no header Authorization. |
| `PIX-1060` | **400** Token de autenticação inválido | O token de autenticação fornecido é inválido. Obtenha um novo token e tente novamente. |
| `PIX-1061` | **400** Token de autenticação expirado | O token de autenticação expirou. Obtenha um novo token usando o endpoint de autenticação. |
| `PIX-1062` | **400** Permissões insuficientes | O participante autenticado não tem permissões suficientes para realizar esta operação. |
| `PIX-1063` | **400** Participante não autorizado | O participante autenticado não está autorizado a realizar esta operação no recurso especificado. |
| `PIX-1064` | **400** Regra de autenticação ou autorização violada | A requisição viola regras de autenticação ou autorização. Verifique suas credenciais e permissões. |
### Chaves Pix
| `code` | Descrição | `detail` |
| ---------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `PIX-1009` | **422** Formato de chave Pix inválido | O formato da chave PIX é inválido para o tipo especificado. Verifique se o formato corresponde ao padrão esperado e tente novamente. |
| `PIX-1010` | **409** Chave Pix já existe | Já existe uma chave PIX com este valor. Use uma chave PIX diferente. |
| `PIX-1011` | **404** Chave Pix não encontrada | A chave PIX especificada não foi encontrada no sistema. Verifique o valor da chave e tente novamente. |
| `PIX-1012` | **400** Limite de chaves Pix excedido | Você atingiu o número máximo de chaves PIX permitido. Exclua uma chave existente antes de criar uma nova. |
| `PIX-1013` | **422** Tipo de chave Pix inválido | O tipo de chave PIX é inválido. Use um tipo de chave PIX válido. |
| `PIX-1014` | **422** Chave Pix expirada | A chave PIX expirou e não pode ser usada. Crie uma nova chave PIX. |
| `PIX-1015` | **400** Chave Pix pendente de confirmação | A chave PIX está pendente de confirmação. Conclua o processo de confirmação. |
| `PIX-1016` | **400** Chave Pix inativa | A chave PIX está inativa e não pode ser usada. Ative a chave PIX. |
| `PIX-1017` | **403** Exclusão de chave Pix não permitida | A chave PIX não pode ser excluída em seu estado atual. Verifique o status da chave. |
| `PIX-1018` | **422** Tipo de conta inválido | O tipo de conta é inválido para esta operação. Use um tipo de conta válido. |
### Reivindicações de chave Pix
| `code` | Descrição | `detail` |
| ---------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `PIX-1019` | **404** Reivindicação de chave Pix não encontrada | A reivindicação de chave PIX especificada não foi encontrada. Verifique o identificador da reivindicação. |
| `PIX-1020` | **409** Reivindicação de chave Pix já existe | Já existe uma reivindicação de chave PIX com este identificador. Use um identificador exclusivo. |
| `PIX-1021` | **422** Status de reivindicação inválido | A reivindicação não está em um status válido para esta operação. Verifique o status da reivindicação. |
| `PIX-1022` | **422** Reivindicação de chave Pix expirada | A reivindicação de chave PIX expirou e não pode ser processada. Crie uma nova reivindicação. |
| `PIX-1023` | **403** Ação de reivindicação não autorizada | Você não está autorizado a realizar esta ação na reivindicação. Verifique suas permissões. |
| `PIX-1024` | **409** Reivindicação já processada | A reivindicação de chave PIX já foi processada e não pode ser modificada. |
| `PIX-1025` | **422** Dados de reivindicação inválidos | Os dados da reivindicação fornecidos são inválidos. Verifique todos os campos e tente novamente. |
| `PIX-1026` | **400** Divergência de Bank ID na reivindicação | Há uma divergência de Bank ID na requisição de reivindicação. Verifique os valores de Bank ID. |
### Transações e pagamentos
| `code` | Descrição | `detail` |
| ---------- | --------------------------------------- | -------------------------------------------------------------------------------------------- |
| `PIX-1027` | **404** Transação não encontrada | A transação especificada não foi encontrada. Verifique o identificador da transação. |
| `PIX-1028` | **409** Transação já existe | Já existe uma transação com este identificador. Use um ID de transação exclusivo. |
| `PIX-1029` | **422** Valor de transação inválido | O valor da transação é inválido. Forneça um valor positivo válido. |
| `PIX-1030` | **400** Saldo insuficiente | A conta não tem saldo suficiente para esta transação. Adicione fundos e tente novamente. |
| `PIX-1031` | **409** Limite de transação excedido | O valor da transação excede os limites configurados. Tente um valor menor. |
| `PIX-1032` | **422** Dados do destinatário inválidos | Os dados do destinatário são inválidos. Verifique todas as informações do destinatário. |
| `PIX-1033` | **422** Transação expirada | A transação expirou e não pode ser processada. Crie uma nova transação. |
| `PIX-1034` | **422** Transação cancelada | A transação foi cancelada e não pode ser processada. |
| `PIX-1035` | **422** Validação de pagamento falhou | A validação do pagamento falhou. Verifique todos os detalhes do pagamento e tente novamente. |
| `PIX-1036` | **400** ID end-to-end inválido | O formato do ID end-to-end é inválido. Use um identificador end-to-end válido. |
### Devoluções
| `code` | Descrição | `detail` |
| ---------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `PIX-1037` | **400** Devolução não permitida | A devolução não é permitida para esta transação. Verifique o status da transação e a elegibilidade para devolução. |
| `PIX-1038` | **422** Motivo de devolução inválido | O código do motivo de devolução é inválido. Use um código de motivo de devolução válido. |
| `PIX-1039` | **422** Valor da devolução excede o original | O valor da devolução excede o valor da transação original. Informe um valor de devolução válido. |
| `PIX-1040` | **400** Prazo de devolução expirado | O prazo de devolução para esta transação expirou. Devoluções não são mais permitidas. |
| `PIX-1041` | **404** Transação original não encontrada | A transação original não foi encontrada para esta devolução. Verifique o identificador da transação. |
### Participantes e contas
| `code` | Descrição | `detail` |
| ---------- | -------------------------------- | ------------------------------------------------------------------------------- |
| `PIX-1042` | **422** Bank ID inválido | O código do Bank ID é inválido. Forneça um código de Bank ID válido. |
| `PIX-1043` | **422** Bank ID não participante | O Bank ID não é participante do sistema PIX. Use um Bank ID participante. |
| `PIX-1044` | **422** Número de conta inválido | O formato do número de conta é inválido. Forneça um número de conta válido. |
| `PIX-1045` | **422** Conta bloqueada | A conta está bloqueada e não pode ser acessada. Entre em contato com o suporte. |
| `PIX-1046` | **400** Conta encerrada | A conta está encerrada e não pode ser acessada. Use uma conta ativa. |
### QR codes
| `code` | Descrição | `detail` |
| ---------- | ---------------------------- | ------------------------------------------------------------------------------------------ |
| `PIX-1047` | **422** QR code inválido | O formato do QR code é inválido ou está corrompido. Verifique o QR code e tente novamente. |
| `PIX-1048` | **404** QR code expirado | O QR code expirou e não pode ser usado. Gere um novo QR code. |
| `PIX-1049` | **422** QR code já utilizado | O QR code já foi utilizado e não pode ser usado novamente. |
### Disponibilidade do trilho
| `code` | Descrição | `detail` |
| ---------- | ---------------------------------- | ----------------------------------------------------------------------------------------------- |
| `PIX-1050` | **503** Serviço JDPI indisponível | O serviço JDPI está temporariamente indisponível. Tente novamente mais tarde. |
| `PIX-1051` | **504** Timeout do serviço JDPI | A requisição ao serviço JDPI atingiu o tempo limite. Tente novamente. |
| `PIX-1052` | **500** Erro interno do JDPI | Ocorreu um erro interno no JDPI. Entre em contato com o suporte se o problema persistir. |
| `PIX-1053` | **429** Muitas requisições | Muitas requisições foram enviadas. Aguarde antes de fazer outra requisição. |
| `PIX-1054` | **400** Erro de conexão com o JDPI | Falha ao conectar com o serviço JDPI. Verifique a disponibilidade do serviço e tente novamente. |
| `PIX-1055` | **502** Erro de serviço externo | `internal error` |
### Fraude, conformidade e regulação
| `code` | Descrição | `detail` |
| ---------- | -------------------------------- | -------------------------------------------------------------------------------------------- |
| `PIX-1056` | **403** Fraude detectada | A transação foi bloqueada devido à detecção de fraude. Entre em contato com o suporte. |
| `PIX-1057` | **403** Violação de conformidade | Foi detectada uma violação de conformidade. Garanta que todos os requisitos sejam atendidos. |
| `PIX-1058` | **403** Restrição regulatória | Uma restrição regulatória se aplica a esta operação. Entre em contato com o suporte. |
## Falhas originadas fora do trilho Pix
***
Uma requisição Pix também pode falhar porque outro serviço da plataforma a recusou. Três faixas de código carregam essas recusas: registros de clientes, autorização e o ledger do Midaz.
### Registros de clientes
| `code` | Descrição | `detail` |
| ---------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `PIX-2000` | **422** Aninhamento inválido de metadados | O objeto metadados não pode conter valores aninhados. Confirme que o valor não está aninhado e tente novamente. |
| `PIX-2001` | **422** Chave de metadados muito longa | A chave de metadados excede o tamanho máximo permitido. Use um nome de chave mais curto. |
| `PIX-2002` | **400** Campos ausentes na requisição | Sua requisição está sem um ou mais campos obrigatórios. Forneça todos os campos obrigatórios e tente novamente. |
| `PIX-2003` | **400** Tipo de campo inválido na requisição | Um ou mais campos têm tipos de dados incorretos. Verifique os tipos dos campos e tente novamente. |
| `PIX-2004` | **400** Parâmetro de caminho inválido | Os parâmetros de caminho estão em formato incorreto. Verifique o formato do parâmetro. |
| `PIX-2005` | **400** Campos inesperados na requisição | A requisição contém mais campos do que o esperado. Envie apenas os campos permitidos conforme a documentação. |
| `PIX-2006` | **422** Limite de paginação excedido | O limite de paginação excede o valor máximo permitido. Use um limite menor. |
| `PIX-2007` | **400** Ordem de classificação inválida | A ordem de classificação deve ser "asc" ou "desc". Use uma ordem de classificação válida. |
| `PIX-2008` | **400** Valor de metadados muito longo | O valor de metadados excede o tamanho máximo permitido. Use um valor mais curto. |
| `PIX-2009` | **409** Conta já associada | A conta pode ser associada a apenas uma conta relacionada. Use uma conta diferente. |
| `PIX-2010` | **400** Requisição inválida | O servidor não conseguiu entender a requisição devido a sintaxe inválida. Verifique o formato da requisição. |
| `PIX-2011` | **400** Parâmetro de consulta inválido | Os parâmetros de consulta estão em formato incorreto. Verifique os valores dos parâmetros. |
| `PIX-2012` | **422** Não é possível excluir o titular | O titular não pode ser excluído devido a contas associadas. Remova as contas associadas primeiro. |
| `PIX-2013` | **400** Headers ausentes na requisição | Parâmetros de header obrigatórios estão ausentes na requisição. Inclua todos os headers obrigatórios. |
| `PIX-2014` | **400** Formato de metadados inválido | O formato do parâmetro metadata está incorreto. Use o formato de metadados correto. |
| `PIX-2015` | **404** ID do titular não encontrado | O ID do titular especificado não existe. Verifique o ID do titular e tente novamente. |
| `PIX-2016` | **404** ID de conta não encontrado | O ID de conta especificado não existe. Verifique o ID de conta e tente novamente. |
| `PIX-2017` | **403** Falha na autenticação do CRM | A autenticação do CRM falhou. Verifique suas credenciais. |
| `PIX-2018` | **409** Erro de associação de documento | O documento apenas pode ser associado a um titular. Use um documento diferente. |
| `PIX-2019` | **500** Erro interno do servidor | `internal error` |
| `PIX-2020` | **503** Erro de conexão com o CRM | `internal error` |
| `PIX-2021` | **504** Timeout do serviço CRM | `internal error` |
| `PIX-2022` | **503** Serviço CRM indisponível | `internal error` |
| `PIX-2023` | **401** Falha na autenticação do CRM | A autenticação do CRM falhou. Verifique suas credenciais. |
| `PIX-2024` | **429** Rate limit do CRM excedido | O rate limit do serviço CRM foi excedido. Aguarde antes de fazer outra requisição. |
### Autorização
| `code` | Descrição | `detail` |
| ---------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `PIX-3000` | **400** Campos ausentes na requisição | Sua requisição está sem um ou mais campos obrigatórios. Forneça todos os campos obrigatórios e tente novamente. |
| `PIX-3001` | **422** Tipo de concessão inválido | O tipo de concessão fornecido é inválido. Use "client\_credentials" para autenticação. |
| `PIX-3002` | **422** Tipo de concessão com campos ausentes | Campos obrigatórios estão ausentes para o tipo de concessão. Forneça client\_id e client\_secret. |
| `PIX-3003` | **422** Tipo de concessão não suportado | O tipo de concessão não é aceito pela aplicação. Use "client\_credentials". |
| `PIX-3004` | **401** Cliente inválido | As credenciais de cliente fornecidas são inválidas. Verifique seu ID do cliente e o Secret do cliente. |
| `PIX-3005` | **400** Requisição inválida | O servidor não conseguiu entender a requisição devido a sintaxe inválida. Verifique o formato da requisição. |
| `PIX-3006` | **400** Erro de conexão com o Access Manager | Falha ao conectar com o serviço Access Manager. Verifique a disponibilidade do serviço e tente novamente. |
| `PIX-3007` | **504** Timeout do Access Manager | `internal error` |
| `PIX-3008` | **503** Serviço Access Manager indisponível | `internal error` |
### Ledger
| `code` | Descrição | `detail` |
| ---------- | ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `PIX-4000` | **503** Erro de conexão com o Midaz | `internal error` |
| `PIX-4001` | **504** Timeout do serviço Midaz | `internal error` |
| `PIX-4002` | **503** Serviço Midaz indisponível | `internal error` |
| `PIX-4003` | **401** Falha na autenticação do Midaz | A autenticação do Midaz falhou. Verifique suas credenciais. |
| `PIX-4004` | **403** Acesso não autorizado ao Midaz | Acesso não autorizado ao serviço Midaz. Verifique suas permissões. |
| `PIX-4005` | **400** Requisição inválida ao Midaz | Requisição inválida para o serviço Midaz. Verifique o formato da requisição. |
| `PIX-4006` | **404** Conta Midaz não encontrada | A conta Midaz especificada não foi encontrada. Verifique o ID da conta e tente novamente. |
| `PIX-4007` | **422** Conta Midaz bloqueada | A conta Midaz está bloqueada e não pode ser acessada. Entre em contato com o suporte. |
| `PIX-4008` | **400** Conta Midaz encerrada | A conta Midaz está encerrada e não pode ser acessada. Entre em contato com o suporte. |
| `PIX-4009` | **422** Saldo Midaz insuficiente | A conta não tem saldo suficiente para esta operação. Adicione fundos e tente novamente. |
| `PIX-4010` | **503** Erro ao buscar saldo do Midaz | `internal error` |
| `PIX-4011` | **500** Falha na transação do Midaz | `internal error` |
| `PIX-4012` | **500** Falha no débito do Midaz | `internal error` |
| `PIX-4013` | **500** Falha no crédito do Midaz | `internal error` |
| `PIX-4014` | **404** Transação Midaz não encontrada | A transação Midaz especificada não foi encontrada. Verifique o ID da transação. |
| `PIX-4015` | **409** Transação Midaz duplicada | Já existe uma transação Midaz com este identificador. Use um ID de transação exclusivo. |
| `PIX-4016` | **422** Valor de transação inválido | O valor da transação é inválido. Forneça um valor positivo válido. |
| `PIX-4017` | **409** Limite de transação Midaz excedido | O valor da transação excede os limites configurados do Midaz. Tente um valor menor. |
## Entrega de notificação
***
Os fluxos de posse de chave Pix enviam um código de uso único por e-mail ou por SMS. Estes códigos relatam uma falha nessa etapa de entrega.
### Entrega por e-mail
| `code` | Descrição | `detail` |
| ---------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `PIX-5000` | **401** Chave de API inválida | A chave de API do SendGrid é inválida, foi excluída ou as permissões mudaram. Verifique sua chave de API. |
| `PIX-5001` | **400** Payload malformado | O payload da requisição da API do SendGrid está malformado. Verifique o formato da requisição. |
| `PIX-5002` | **403** Permissões insuficientes | Você tem permissões insuficientes para esta operação do SendGrid. Verifique as permissões da sua conta. |
| `PIX-5003` | **429** Rate limit excedido | O rate limit do SendGrid foi excedido. Aguarde antes de fazer outra requisição. |
| `PIX-5004` | **400** Erro de conexão com o SendGrid | Falha ao conectar com o serviço de e-mail do SendGrid. Verifique a disponibilidade do serviço e tente novamente. |
| `PIX-5005` | **504** Timeout do serviço SendGrid | A requisição ao serviço de e-mail do SendGrid atingiu o tempo limite. Tente novamente. |
| `PIX-5006` | **503** Serviço SendGrid indisponível | O serviço de e-mail do SendGrid está temporariamente indisponível. Tente novamente mais tarde. |
### Entrega por SMS
| `code` | Descrição | `detail` |
| ---------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `PIX-6000` | **403** Permissão negada | Permissão negada para a operação de SMS do Twilio. Verifique as permissões da sua conta e tente novamente. |
| `PIX-6001` | **401** Token de acesso inválido | O token de acesso do Twilio é inválido. Verifique suas credenciais de autenticação. |
| `PIX-6002` | **401** Falha na autenticação | A autenticação de SMS do Twilio falhou. Verifique as credenciais da sua conta. |
| `PIX-6003` | **400** Limitação de conta de avaliação | Este recurso não está disponível para contas de avaliação. Atualize sua conta Twilio. |
| `PIX-6004` | **400** Formato de URL inválido | Formato de URL inválido para o webhook do Twilio. Verifique o formato da URL e tente novamente. |
| `PIX-6005` | **400** Violação de protocolo HTTP | Violação de protocolo HTTP na requisição do Twilio. Verifique o formato da requisição. |
| `PIX-6006` | **429** Rate limit de SMS excedido | O rate limit de envio de SMS do Twilio foi excedido. Aguarde antes de enviar mais mensagens. |
| `PIX-6007` | **400** Telefone não capacitado para SMS | O número de telefone remetente não é capacitado para SMS. Use um número de telefone com suporte a SMS. |
| `PIX-6008` | **400** Limite de resposta excedido | O limite de mensagens de resposta do TwiML foi excedido. Reduza o número de mensagens de resposta. |
| `PIX-6009` | **400** Verb usado para a requisição de SMS não é permitido | Verb inválido para a resposta de SMS. Use um Verb do TwiML válido. |
| `PIX-6010` | **400** Telefone inválido para avaliação | Número de telefone de destino inválido para o modo de avaliação. Verifique o número ou atualize sua conta. |
| `PIX-6011` | **400** Número de telefone remetente não verificado | O número de telefone remetente não está verificado para sua conta Twilio. Verifique o número. |
| `PIX-6012` | **400** Número de telefone remetente não verificado | O número de telefone remetente não está verificado para sua conta Twilio. Verifique o número. |
| `PIX-6013` | **400** Número de telefone de destino inválido | O formato do número de telefone de destino é inválido. Use um número de telefone válido. |
| `PIX-6014` | **400** Número de telefone remetente inválido | O formato do número de telefone remetente é inválido. Use um número de telefone válido. |
| `PIX-6015` | **400** Erro de conexão com o Twilio | Falha ao conectar com o serviço de SMS do Twilio. Verifique a disponibilidade do serviço e tente novamente. |
| `PIX-6016` | **504** Timeout do serviço Twilio | A requisição ao serviço de SMS do Twilio atingiu o tempo limite. Tente novamente. |
| `PIX-6017` | **503** Serviço Twilio indisponível | O serviço de SMS do Twilio está temporariamente indisponível. Tente novamente mais tarde. |
## Motivos de rejeição de reembolso do MED
***
Uma requisição de reembolso do MED que este participante analisa e rejeita carrega um motivo de rejeição numerado. O domínio usa os valores 0, 1, 3 e 4.
| Valor | Rótulo | O que significa |
| ----- | ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `0` | Falta de saldo | A conta do cliente não tem saldo para cobrir o reembolso. |
| `1` | Relacionamento encerrado | O relacionamento com o cliente está encerrado. |
| `3` | Generico | Um motivo que os outros três valores não cobrem. |
| `4` | Requisicao invalida | A requisição de reembolso é inválida. Este valor se aplica quando o motivo do reembolso é uma falha operacional. |
## Códigos de motivo de devolução Pix
***
Um Pix devolvido carrega um motivo de devolução próprio do Bacen, separado dos códigos `PIX-NNNN` acima. Esta referência de API documenta os valores permitidos no campo que os carrega. Esse campo é `codigoDevolucao` em um crédito recebido e na visualização de status do crédito de reembolso. Em uma requisição de reembolso, é `code`.