Códigos de erro

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`

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.

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.

Rotas: POST /v1/withdraw/, POST /v1/withdraw/qrcode, GET /v1/withdraw/, POST /v1/internal-transfer/, GET /v1/internal-transfer/

Código	HTTP	Mensagem	O que fazer
`PZS200`	422	Saque não permitido para esta conta no momento.	Saque não habilitado.
`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.

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.

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

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

Código	HTTP	Mensagem	O que fazer
`PZG404`	404	Recurso não encontrado.	Recurso não existe.
`PZG429`	429	Muitas requisições em curto período. Tente novamente em instantes.	Aguarde o `retryAfterSeconds`.