Códigos de erro

Tratamento de erros Autenticação Glossário (códigos HTTP)

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, 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
429	Rate limit	Aguarde o `retryAfterSeconds`
502 / 504	Falha/timeout da instituição financeira	Retry com backoff
503	Indisponível no momento	Repita após o `retryAfterSeconds`
500	Erro interno do servidor	Tente de novo; persistindo, suporte com `requestId`

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

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`	503	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`	502	Não foi possível gerar o depósito junto à instituição financeira. Tente novamente.	Falha no recebedor; tente de novo.
`PZD103`	504	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

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`	503	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 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

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

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`	502	Erro de comunicação com a instituição financeira.	Tente de novo.
`PZI111`	504	A instituição financeira demorou para responder. Tente novamente.	Timeout; tente de novo.
`PZF500`	503	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`.

Códigos de erro

Nesta página