# Códigos de erro (/docs/pix-processamento/error-codes) Toda resposta de erro segue o mesmo envelope. Programe sua lógica pelo `errorCode` (estável), não pela `message` (pode mudar). | campo | descrição | | ------------------- | ----------------------------------------------------------------------------------------- | | `errorCode` | Código estável (ex.: `PZD600`). Use-o na sua lógica, não a mensagem. | | `message` | Texto legível, pode mudar. | | `statusCode` | HTTP da resposta. | | `requestId` | Identificador da requisição (informe ao suporte). | | `details[]` | Em validação (400), lista campo + motivo por erro. | | `retryAfterSeconds` | Em 429, 503 e nos 424 de indisponibilidade, segundos sugeridos para repetir a requisição. | ## HTTP por origem [#http-por-origem] | HTTP | Significa | O que fazer | | -------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 400 | Dado inválido | Não retentar; corrija o pedido | | 401 | Não autenticado | Verifique o token | | 403 | Sem permissão / IP | Não retentar; cheque o escopo do token / o IP | | 404 | Não encontrado | Confira o id/clientReference | | 409 | Conflito | Consulte o estado antes de repetir | | 410 | Expirado | Recurso não existe mais | | 422 | Regra de negócio | Corrija conforme a mensagem | | 424 | Falha, recusa, timeout ou indisponibilidade da instituição financeira | Retry com backoff; em criação (depósito, saque, transferência) com timeout, consulte o estado via `clientReference` antes de recriar | | 429 | Rate limit | Aguarde o `retryAfterSeconds` | | 500 | Erro interno da PayZu | Tente de novo; persistindo, suporte com `requestId` | | 503 | PayZu temporariamente indisponível | Repita após o `retryAfterSeconds` | | Timeout (rede) | Sem resposta HTTP dentro do prazo, não é um status retornado pela API | A operação pode ter sido aplicada; consulte o estado via `clientReference` antes de recriar | > 5xx significa sempre problema na PayZu; 424 significa problema na instituição financeira. A aplicação não emite 502/504: se receber um deles, veio de proxy/CDN no caminho, não da API. ## Transversais [#transversais] Estes podem aparecer em qualquer rota `/v1` autenticada, independente do fluxo. | Código | HTTP | Mensagem | O que fazer | | -------- | ---- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `PZV001` | 400 | Dados inválidos. Verifique os campos informados. | Veja `details[]`: aponta o campo e o motivo. | | `PZI100` | 500 | Erro interno ao processar a solicitação. | Tente de novo; persistindo, suporte com `requestId`. | | `PZF503` | 503 | Serviço temporariamente indisponível. Tente novamente em instantes. | Indisponibilidade da PayZu; retry com backoff. | | `PZA100` | 401 | Autenticação necessária ou token inválido. | Envie `Authorization: Bearer` válido e ativo. | | `PZA200` | 403 | Operação não permitida para este token/escopo. | Token sem a permissão exigida pela rota, ou o subdomínio de acesso não corresponde à conta. | | `PZA203` | 403 | Acesso não permitido a partir deste endereço de IP. | IP fora da whitelist (saque/transferência). Libere o IP nas configurações. | | `PZA204` | 403 | Conta bloqueada para alterações. Desbloqueie a conta antes de alterar. | Retornado por `PATCH /v1/user` e demais alterações de configuração quando a conta está bloqueada para alterações. Contate o suporte para desbloquear. | ## Depósito / Cash-in [#depósito--cash-in] Rotas: `POST /v1/pix/`, `POST /v1/transactions/`, `GET /v1/pix/`, `GET /v1/pix/qr-code/:transactionId`, `GET /v1/user/deposit-pending/` e `/:id` | Código | HTTP | Mensagem | O que fazer | | -------- | ---- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `PZD200` | 422 | Depósito não permitido para esta conta. | Depósito não habilitado; contate o suporte. | | `PZD201` | 422 | Depósitos de CNPJ não estão liberados para esta conta. | Pagador CNPJ não habilitado. | | `PZD500` | 424 | Nenhuma instituição financeira disponível no momento. Tente novamente em instantes. | Repita após o `retryAfterSeconds`. | | `PZD600` | 400 | O valor mínimo do depósito é `{min}`. | Valor abaixo do mínimo. | | `PZD601` | 400 | O valor máximo do depósito é `{max}`. | Valor acima do máximo. | | `PZD602` | 400 | Para depósitos acima de `{limite}` é obrigatório informar o documento. | Envie `generatedDocument`. | | `PZD100` | 424 | Não foi possível gerar o depósito junto à instituição financeira. Tente novamente. | Falha no recebedor; tente de novo. | | `PZD103` | 424 | O tempo limite de processamento do depósito foi atingido. Tente novamente. | Timeout no processamento. Consulte o estado via `clientReference` antes de recriar; o depósito pode ter sido concluído. | ## Saque / Cash-out [#saque--cash-out] Rotas: `POST /v1/withdraw/`, `POST /v1/withdraw/qrcode`, `GET /v1/withdraw/` | Código | HTTP | Mensagem | O que fazer | | -------- | ---- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | | `PZS200` | 422 | Saque não permitido para esta conta no momento. | Saque não habilitado. | | `PZS201` | 422 | Saque para CNPJ permitido apenas para favorecidos cadastrados. | Cadastre o favorecido CNPJ antes de sacar. | | `PZS202` | 422 | Limite diário de saque excedido. | Aguarde o próximo dia ou solicite ajuste de limite. | | `PZC200` | 422 | Saldo insuficiente para esta operação. | Saldo indisponível; também retornado em `POST /v1/internal-transfer/`. | | `PZS102` | 422 | Pagamento rejeitado pela instituição financeira do recebedor. | Rejeição no destino; confira os dados do favorecido antes de repetir. | | `PZS500` | 424 | Nenhuma instituição financeira disponível para o saque no momento. Tente novamente em instantes. | Repita após o `retryAfterSeconds`. | | `PZS600` | 400 | O valor mínimo do saque é `{min}`. | Valor abaixo do mínimo. | | `PZS601` | 400 | O valor máximo do saque é `{max}`. | Valor acima do máximo. | | `PZS602` | 400 | O valor do saque está fora dos limites da instituição financeira. | Ajuste aos limites do recebedor. | | `PZS603` | 400 | O valor informado (`{a}`) não corresponde ao valor do QR Code (`{b}`). | Use o valor exato do QR. | | `PZS604` | 400 | É obrigatório informar o valor. | QR sem valor fixo; informe o valor. | ## Transferência interna [#transferência-interna] Rotas: `POST /v1/internal-transfer/`, `GET /v1/internal-transfer/` O `PZC200` (saldo insuficiente), listado na seção de saque, também é retornado aqui. | Código | HTTP | Mensagem | O que fazer | | -------- | ---- | ------------------------------------------------------------------ | --------------------------------------------------------- | | `PZC201` | 422 | Conta destinatária indisponível. | A conta destino não pode receber no momento. | | `PZC202` | 422 | O valor da transferência não cobre a taxa de cash-in do recebedor. | Aumente o valor da transferência. | | `PZC300` | 404 | Conta destinatária inválida ou não encontrada. | Confira o `receiverAccountNumber`. | | `PZC301` | 404 | Transferência interna não encontrada. | Não localizada para sua conta. | | `PZC400` | 403 | A conta pagadora não pertence ao solicitante. | O `payerAccountNumber` deve ser a conta do próprio token. | | `PZC401` | 403 | Transferência interna não habilitada para esta conta. | Não habilitada; contate o suporte. | | `PZC600` | 400 | Não é permitido transferir para a própria conta. | Informe uma conta destino diferente da pagadora. | | `PZC602` | 400 | O valor mínimo da transferência é `{min}`. | Valor abaixo do mínimo. | | `PZC603` | 400 | O valor máximo da transferência é `{max}`. | Valor acima do máximo. | ## Chave Pix / DICT / QR [#chave-pix--dict--qr] Rotas: `GET /v1/pix/key`, `POST /v1/pix/qrcode/read`, `POST /v1/withdraw/qrcode`, `GET /v1/user/pix-keys/` | Código | HTTP | Mensagem | O que fazer | | -------- | ---- | --------------------------------------------------------------------------------------- | ---------------------------------- | | `PZK101` | 424 | Não foi possível consultar o QR Code junto à instituição financeira. | Tente de novo. | | `PZK200` | 422 | Chave Pix inválida. | Chave inválida. | | `PZK201` | 422 | A chave Pix não corresponde ao documento do destinatário. | Chave não bate com o documento. | | `PZK300` | 404 | Chave Pix não encontrada. | Chave não localizada no DICT. | | `PZK301` | 404 | QR Code não encontrado. | QR não localizado. | | `PZK310` | 410 | Este QR Code expirou ou foi removido pela instituição financeira recebedora. | Solicite um novo QR. | | `PZK400` | 403 | Consulta de chave Pix não habilitada para o usuário. | Não habilitado; contate o suporte. | | `PZK401` | 403 | Leitura de QR Code não habilitada para o usuário. | Não habilitado. | | `PZK600` | 400 | Chave Pix inválida. Formatos: CPF, CNPJ, e-mail, telefone (+55...) ou aleatória (UUID). | Corrija o formato. | | `PZK601` | 400 | QR Code inválido ou mal formatado. | QR não pôde ser lido. | ## Consulta / Comprovante / Conta [#consulta--comprovante--conta] Rotas: `GET /v1/status/`, `GET /v1/user/transactions/` e `/:id`, `GET /v1/user/bank-statements/` e `/:id`, `POST /v1/user/report/:id/download` | Código | HTTP | Mensagem | O que fazer | | -------- | ---- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `PZC210` | 409 | Já existe uma operação com este identificador. Verifique o clientReference informado. | `clientReference` duplicado; use outro ou consulte a operação. | | `PZC310` | 404 | Transação não encontrada. | Não localizada para sua conta. | | `PZC320` | 422 | Transação ainda não processada. | Comprovante indisponível enquanto pendente. | | `PZC321` | 422 | Comprovante indisponível: transação cancelada sem documento. | Transação cancelada sem comprovante. | | `PZI103` | 500 | Dado interno ausente para concluir a operação. | Tente mais tarde; persistindo, suporte com `requestId`. | ## Infrações (MED) [#infrações-med] Rotas: `GET /v1/user/infractions/` e `/:id`, `POST /v1/user/infractions/:id/defenses` | Código | HTTP | Mensagem | O que fazer | | -------- | ---- | ------------------------------------ | -------------------------------------------------------------------------------------- | | `PZK210` | 409 | Infração já encerrada. | A infração não aceita mais ações; consulte o status atual. | | `PZK211` | 422 | Infração não está em análise manual. | Ação disponível apenas quando a infração está em análise manual. | | `PZK212` | 409 | Defesa já enviada. | Já existe defesa para esta infração; consulte `GET /v1/user/infractions/:id/defenses`. | ## Instituição financeira [#instituição-financeira] Aparecem nas rotas que consultam a instituição financeira em tempo real. | Código | HTTP | Mensagem | O que fazer | | -------- | ---- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `PZI101` | 500 | Operação não suportada para esta instituição financeira. | Operação não suportada pelo recebedor. | | `PZI110` | 424 | Erro de comunicação com a instituição financeira. | Tente de novo. | | `PZI111` | 424 | A instituição financeira demorou para responder. Tente novamente. | Timeout; em criação (depósito, saque, transferência), consulte o estado via `clientReference` antes de recriar. | | `PZF500` | 424 | Instituição financeira temporariamente indisponível. Tente novamente em instantes. | Repita após o `retryAfterSeconds`. | ## Genéricos [#genéricos] | Código | HTTP | Mensagem | O que fazer | | -------- | ---- | ------------------------------------------------------------------ | ---------------------------------------------- | | `PZG404` | 404 | Recurso não encontrado. | Recurso não existe. | | `PZG409` | 409 | A solicitação conflita com o estado atual do recurso. | Consulte o estado antes de repetir. | | `PZG410` | 410 | Este recurso não está mais disponível. | Recurso expirado ou removido. | | `PZG422` | 422 | Não foi possível processar a solicitação. | Regra de negócio; corrija conforme a mensagem. | | `PZG423` | 422 | O valor excede o limite permitido para esta operação. | Reduza o valor ou revise seus limites. | | `PZG429` | 429 | Muitas requisições em curto período. Tente novamente em instantes. | Aguarde o `retryAfterSeconds`. |