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 | On creation operations (deposit, withdrawal, transfer), query by clientReference before recreating; retry with backoff only for idempotent/query operations |
| 503 | Temporarily unavailable | Retry after the retryAfterSeconds |
| 500 | Internal server error | Try again; if it persists, contact support with requestId |
Cross-cutting
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. |
PZA204 | 403 | Conta bloqueada para alterações. Desbloqueie a conta antes de alterar. | Returned by PATCH /v1/user and other configuration changes when the account is locked for changes. Contact support to unlock. |
Deposit / Cash-in
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. |
PZD103 | 504 | O tempo limite de processamento do depósito foi atingido. Tente novamente. | Processing timeout. Check the state via clientReference before creating a new one; the deposit may have completed. |
Withdrawal / Cash-out
Routes: POST /v1/withdraw/, POST /v1/withdraw/qrcode, GET /v1/withdraw/
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZS200 | 422 | Saque não permitido para esta conta no momento. | Withdrawal not enabled. |
PZS201 | 422 | Saque para CNPJ permitido apenas para favorecidos cadastrados. | Register the CNPJ beneficiary before withdrawing. |
PZS202 | 422 | Limite diário de saque excedido. | Wait for the next day or request a limit adjustment. |
PZC200 | 422 | Saldo insuficiente para esta operação. | Insufficient balance; also returned on POST /v1/internal-transfer/. |
PZS102 | 422 | Pagamento rejeitado pela instituição financeira do recebedor. | Rejected at the destination; check the beneficiary data before retrying. |
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. |
Internal transfer
Routes: POST /v1/internal-transfer/, GET /v1/internal-transfer/
PZC200 (insufficient balance), listed in the withdrawal section, is also returned here.
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZC201 | 422 | Conta destinatária indisponível. | The destination account cannot receive at the moment. |
PZC202 | 422 | O valor da transferência não cobre a taxa de cash-in do recebedor. | Increase the transfer amount. |
PZC300 | 404 | Conta destinatária inválida ou não encontrada. | Check the receiverAccountNumber. |
PZC301 | 404 | Transferência interna não encontrada. | Not found for your account. |
PZC400 | 403 | A conta pagadora não pertence ao solicitante. | The payerAccountNumber must be the token's own account. |
PZC401 | 403 | Transferência interna não habilitada para esta conta. | Not enabled; contact support. |
PZC600 | 400 | Não é permitido transferir para a própria conta. | Provide a destination account different from the payer. |
PZC602 | 400 | O valor mínimo da transferência é {min}. | Amount below the minimum. |
PZC603 | 400 | O valor máximo da transferência é {max}. | Amount above the maximum. |
Pix key / DICT / QR
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. |
Query / Proof / Account
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. |
Infractions (MED)
Routes: GET /v1/user/infractions/ and /:id, POST /v1/user/infractions/:id/defenses
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZK210 | 409 | Infração já encerrada. | The infraction no longer accepts actions; query the current status. |
PZK211 | 422 | Infração não está em análise manual. | Action available only while the infraction is under manual review. |
PZK212 | 409 | Defesa já enviada. | A defense already exists for this infraction; query GET /v1/user/infractions/:id/defenses. |
Financial institution
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. |
Generic
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZG404 | 404 | Recurso não encontrado. | Resource does not exist. |
PZG409 | 409 | A solicitação conflita com o estado atual do recurso. | Query the state before retrying. |
PZG410 | 410 | Este recurso não está mais disponível. | Resource expired or removed. |
PZG422 | 422 | Não foi possível processar a solicitação. | Business rule; fix according to the message. |
PZG423 | 422 | O valor excede o limite permitido para esta operação. | Reduce the amount or review your limits. |
PZG429 | 429 | Muitas requisições em curto período. Tente novamente em instantes. | Wait for the retryAfterSeconds. |
Pix key types
Tipos de chave Pix aceitos pela API Pix Processamento, formato esperado de cada um e regras de validação.
Glossary
Termos, siglas, status e campos que aparecem na Pix Processamento. Se você ficou travado em uma sigla do Bacen ou um campo da API, é aqui. Tudo em PT com o nome original quando relevante.