Códigos de erro
Todos os erros que a API pode devolver, com o código estável pra você programar em cima, o que cada um significa e como o seu sistema deve reagir.
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 | 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, pagamento Pix, 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
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 (pagamento Pix/transferência). Libere o IP nas configurações. |
PZA204 | 403 | Conta bloqueada para alterações. Desbloqueie a conta antes de alterar. | Retornado nas alterações de configuração da conta, incluindo criar, editar, remover e rotacionar o segredo de webhook. A trava é avaliada antes da existência do recurso: com a conta bloqueada, um {id} inexistente responde 403, não 404. Contate o suporte para desbloquear. |
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 R$ 2.000,00 é 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. |
Pagamento Pix / 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. | Pagamento Pix não habilitado. |
PZS201 | 422 | Saque para CNPJ permitido apenas para favorecidos cadastrados. | Cadastre o favorecido CNPJ antes de pagar. |
PZS202 | 422 | Limite diário de saque excedido. | Aguarde o próximo dia; o limite e o consumo estão em DailyWithdrawLimit no GET /user. |
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
Rotas: POST /v1/internal-transfer/, GET /v1/internal-transfer/
O PZC200 (saldo insuficiente), listado na seção de pagamento Pix, 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
Rotas: GET /v1/pix/key, POST /v1/pix/qrcode/read, POST /v1/withdraw/qrcode
| 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
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)
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. |
PZK212 | 409 | Defesa já enviada. | Já existe defesa para esta infração; consulte GET /v1/user/infractions/:id/defenses. |
Reenvio de callback
Três rotas reenviam callback, cada uma com seus próprios códigos.
POST /v1/user/callbacks/resend/webhook/:webhookId
| Código | HTTP | Mensagem | O que fazer |
|---|---|---|---|
PZW300 | 404 | Webhook não encontrado, está inativo, ou não pertence ao usuário | Confira o webhookId e se o webhook está ativo na conta. |
PZW310 | 404 | Nenhum callback falho encontrado para o webhook | Não há entrega falha para reenviar nesse webhook. |
POST /v1/user/callbacks/resend
Reenvio em lote, por filtros.
| Código | HTTP | Mensagem | O que fazer |
|---|---|---|---|
PZG404 | 404 | Nenhuma transação encontrada para os critérios fornecidos | Nenhuma transação casa com a janela e os filtros enviados; revise os critérios. |
POST /v1/user/callbacks/resend/:transactionId
Reenvio de uma transação.
| Código | HTTP | Mensagem | O que fazer |
|---|---|---|---|
PZG404 | 404 | Transação não encontrada ou sem callback configurado | Confira o transactionId e se existe callback configurado para ele. |
As três rotas devolvem PZG422 quando o limite de reenvio é atingido. Esse código está na tabela de genéricos.
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. | A instituição do recebedor não suporta a operação. Não repita a chamada; use outra chave ou outro meio de pagamento. |
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, pagamento Pix, 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
| 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. |