Error codes

Every error response follows the same envelope. Program your logic against the errorCode (stable), not the message (may change).

field	description
`errorCode`	Stable code (e.g. `PZD600`). Use it in your logic, not the message.
`message`	Human-readable text, may change.
`statusCode`	HTTP status of the response.
`requestId`	Request identifier (provide it to support).
`details[]`	On validation (400), lists field + reason per error.
`retryAfterSeconds`	On 429/503, suggested seconds to retry the request.

HTTP by origin

HTTP	Means	What to do
400	Invalid data	Do not retry; fix the request
401	Not authenticated	Check the token
403	No permission / IP	Do not retry; check the token scope / the IP
404	Not found	Confirm the id/clientReference
409	Conflict	Query the state before retrying
410	Expired	Resource no longer exists
422	Business rule	Fix according to the message
429	Rate limit	Wait for the `retryAfterSeconds`
502 / 504	Financial institution failure/timeout	Retry with backoff
503	Temporarily unavailable	Retry after the `retryAfterSeconds`
500	Internal server error	Try again; if it persists, contact support with `requestId`

These can appear on any authenticated /v1 route, regardless of the flow.

Code	HTTP	Message	What to do
`PZV001`	400	Dados inválidos. Verifique os campos informados.	See `details[]`: points to the field and the reason.
`PZI100`	500	Erro interno ao processar a solicitação.	Try again; if it persists, contact support with `requestId`.
`PZA100`	401	Autenticação necessária ou token inválido.	Send a valid and active `Authorization: Bearer`.
`PZA200`	403	Operação não permitida para este token/escopo.	Token lacks the permission required by the route, or the access subdomain does not match the account.
`PZA203`	403	Acesso não permitido a partir deste endereço de IP.	IP outside the whitelist (withdrawal/transfer). Allow the IP in the settings.

Routes: POST /v1/pix/, POST /v1/transactions/, GET /v1/pix/, GET /v1/pix/qr-code/:transactionId, GET /v1/user/deposit-pending/ and /:id

Code	HTTP	Message	What to do
`PZD200`	422	Depósito não permitido para esta conta.	Deposit not enabled; contact support.
`PZD201`	422	Depósitos de CNPJ não estão liberados para esta conta.	CNPJ payer not enabled.
`PZD500`	503	Nenhuma instituição financeira disponível no momento. Tente novamente em instantes.	Retry after the `retryAfterSeconds`.
`PZD600`	400	O valor mínimo do depósito é `{min}`.	Amount below the minimum.
`PZD601`	400	O valor máximo do depósito é `{max}`.	Amount above the maximum.
`PZD602`	400	Para depósitos acima de `{limite}` é obrigatório informar o documento.	Send `generatedDocument`.
`PZD100`	502	Não foi possível gerar o depósito junto à instituição financeira. Tente novamente.	Failure at the receiver; try again.

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

Code	HTTP	Message	What to do
`PZS200`	422	Saque não permitido para esta conta no momento.	Withdrawal not enabled.
`PZS500`	503	Nenhuma instituição financeira disponível para o saque no momento. Tente novamente em instantes.	Retry after the `retryAfterSeconds`.
`PZS600`	400	O valor mínimo do saque é `{min}`.	Amount below the minimum.
`PZS601`	400	O valor máximo do saque é `{max}`.	Amount above the maximum.
`PZS602`	400	O valor do saque está fora dos limites da instituição financeira.	Adjust to the receiver's limits.
`PZS603`	400	O valor informado (`{a}`) não corresponde ao valor do QR Code (`{b}`).	Use the exact QR value.
`PZS604`	400	É obrigatório informar o valor.	QR without a fixed value; provide the amount.

Routes: GET /v1/pix/key, POST /v1/pix/qrcode/read, POST /v1/withdraw/qrcode, GET /v1/user/pix-keys/

Code	HTTP	Message	What to do
`PZK101`	502	Não foi possível consultar o QR Code junto à instituição financeira.	Try again.
`PZK200`	422	Chave Pix inválida.	Invalid key.
`PZK201`	422	A chave Pix não corresponde ao documento do destinatário.	Key does not match the document.
`PZK300`	404	Chave Pix não encontrada.	Key not found in DICT.
`PZK301`	404	QR Code não encontrado.	QR not found.
`PZK310`	410	Este QR Code expirou ou foi removido pela instituição financeira recebedora.	Request a new QR.
`PZK400`	403	Consulta de chave Pix não habilitada para o usuário.	Not enabled; contact support.
`PZK401`	403	Leitura de QR Code não habilitada para o usuário.	Not enabled.
`PZK600`	400	Chave Pix inválida. Formatos: CPF, CNPJ, e-mail, telefone (+55...) ou aleatória (UUID).	Fix the format.
`PZK601`	400	QR Code inválido ou mal formatado.	QR could not be read.

Routes: GET /v1/status/, GET /v1/user/transactions/ and /:id, GET /v1/user/bank-statements/ and /:id, POST /v1/user/report/:id/download

Code	HTTP	Message	What to do
`PZC210`	409	Já existe uma operação com este identificador. Verifique o clientReference informado.	Duplicate `clientReference`; use another one or query the operation.
`PZC310`	404	Transação não encontrada.	Not found for your account.
`PZC320`	422	Transação ainda não processada.	Proof unavailable while pending.
`PZC321`	422	Comprovante indisponível: transação cancelada sem documento.	Transaction cancelled without proof.
`PZI103`	500	Dado interno ausente para concluir a operação.	Try again later; if it persists, contact support with `requestId`.

Appear on the routes that query the financial institution in real time.

Code	HTTP	Message	What to do
`PZI101`	500	Operação não suportada para esta instituição financeira.	Operation not supported by the receiver.
`PZI110`	502	Erro de comunicação com a instituição financeira.	Try again.
`PZI111`	504	A instituição financeira demorou para responder. Tente novamente.	Timeout; try again.
`PZF500`	503	Instituição financeira temporariamente indisponível. Tente novamente em instantes.	Retry after the `retryAfterSeconds`.

Code	HTTP	Message	What to do
`PZG404`	404	Recurso não encontrado.	Resource does not exist.
`PZG429`	429	Muitas requisições em curto período. Tente novamente em instantes.	Wait for the `retryAfterSeconds`.