Error codes
All errors the API can return, with the stable code you should code against, what each one means, and how your system should react.
Every error response follows the same envelope. Code your logic against errorCode (stable), not 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 (share it with support). |
details[] | On validation (400), lists field + reason per error. |
retryAfterSeconds | On 429, 503 and 424 unavailability responses, suggested seconds before retrying the request. |
HTTP by origin
| HTTP | Meaning | 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 / IP |
| 404 | Not found | Check the id/clientReference |
| 409 | Conflict | Query the state before retrying |
| 410 | Expired | Resource no longer exists |
| 422 | Business rule | Fix as per the message |
| 424 | Failure, rejection, timeout or unavailability of the financial institution | Retry with backoff; on creation (deposit, Pix payment, transfer) with timeout, query the state via clientReference before recreating |
| 429 | Rate limit | Wait for retryAfterSeconds |
| 500 | PayZu internal error | Retry; if it persists, contact support with requestId |
| 503 | PayZu temporarily unavailable | Retry after retryAfterSeconds |
| Timeout (network) | No HTTP response within the deadline; not a status returned by the API | The operation may have been applied; query the state via clientReference before recreating |
5xx always means a PayZu-side problem; 424 means a financial-institution-side problem. The application does not emit 502/504: if you receive one, it came from a proxy/CDN in the path, not from the API.
Cross-cutting
These can appear on any authenticated /v1 route, regardless of the flow.
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZV001 | 400 | Invalid data. Check the provided fields. | See details[]: it points to the field and the reason. |
PZI100 | 500 | Internal error processing the request. | Retry; if it persists, contact support with requestId. |
PZF503 | 503 | Service temporarily unavailable. Try again shortly. | PayZu unavailability; retry with backoff. |
PZA100 | 401 | Authentication required or invalid token. | Send a valid, active Authorization: Bearer. |
PZA200 | 403 | Operation not allowed for this token/scope. | Token lacks the permission required by the route, or the access subdomain does not match the account. |
PZA203 | 403 | Access not allowed from this IP address. | IP outside the whitelist (Pix payment/transfer). Allowlist the IP in the settings. |
PZA204 | 403 | Account locked for changes. Unlock the account before changing it. | Returned on account configuration changes, including creating, editing, removing and rotating the webhook secret. The lock is evaluated before the resource existence: with the account locked, a non-existent {id} responds 403, not 404. 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 | Deposit not allowed for this account. | Deposit not enabled; contact support. |
PZD201 | 422 | CNPJ deposits are not enabled for this account. | CNPJ payer not enabled. |
PZD500 | 424 | No financial institution available at the moment. Try again shortly. | Retry after retryAfterSeconds. |
PZD600 | 400 | The minimum deposit amount is {min}. | Amount below the minimum. |
PZD601 | 400 | The maximum deposit amount is {max}. | Amount above the maximum. |
PZD602 | 400 | For deposits above R$ 2,000.00 the document is required. | Send generatedDocument. |
PZD100 | 424 | Could not generate the deposit at the financial institution. Try again. | Failure at the receiver; try again. |
PZD103 | 424 | Deposit processing timeout reached. Try again. | Processing timeout. Query the state via clientReference before recreating; the deposit may have been completed. |
Pix payment / Cash-out
Routes: POST /v1/withdraw/, POST /v1/withdraw/qrcode, GET /v1/withdraw/
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZS200 | 422 | Withdrawal not allowed for this account at the moment. | Pix payment not enabled. |
PZS201 | 422 | Withdrawal to CNPJ allowed only for registered beneficiaries. | Register the CNPJ beneficiary before paying. |
PZS202 | 422 | Daily withdrawal limit exceeded. | Wait for the next day; the limit and its usage are in DailyWithdrawLimit on GET /user. |
PZC200 | 422 | Insufficient balance for this operation. | Balance unavailable; also returned on POST /v1/internal-transfer/. |
PZS102 | 422 | Payment rejected by the receiver's financial institution. | Rejection at the destination; check the beneficiary data before retrying. |
PZS500 | 424 | No financial institution available for the withdrawal at the moment. Try again shortly. | Retry after retryAfterSeconds. |
PZS600 | 400 | The minimum withdrawal amount is {min}. | Amount below the minimum. |
PZS601 | 400 | The maximum withdrawal amount is {max}. | Amount above the maximum. |
PZS602 | 400 | The withdrawal amount is outside the financial institution's limits. | Adjust to the receiver's limits. |
PZS603 | 400 | The provided amount ({a}) does not match the QR Code amount ({b}). | Use the exact QR amount. |
PZS604 | 400 | The amount is required. | QR without a fixed amount; provide the amount. |
Internal transfer
Routes: POST /v1/internal-transfer/, GET /v1/internal-transfer/
PZC200 (insufficient balance), listed in the Pix payment section, is also returned here.
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZC201 | 422 | Destination account unavailable. | The destination account cannot receive at the moment. |
PZC202 | 422 | The transfer amount does not cover the receiver's cash-in fee. | Increase the transfer amount. |
PZC300 | 404 | Invalid or not found destination account. | Check receiverAccountNumber. |
PZC301 | 404 | Internal transfer not found. | Not located for your account. |
PZC400 | 403 | The payer account does not belong to the requester. | payerAccountNumber must be the token's own account. |
PZC401 | 403 | Internal transfer not enabled for this account. | Not enabled; contact support. |
PZC600 | 400 | Transferring to your own account is not allowed. | Provide a destination account different from the payer. |
PZC602 | 400 | The minimum transfer amount is {min}. | Amount below the minimum. |
PZC603 | 400 | The maximum transfer amount is {max}. | Amount above the maximum. |
Pix key / DICT / QR
Routes: GET /v1/pix/key, POST /v1/pix/qrcode/read, POST /v1/withdraw/qrcode
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZK101 | 424 | Could not query the QR Code at the financial institution. | Try again. |
PZK200 | 422 | Invalid Pix key. | Invalid key. |
PZK201 | 422 | The Pix key does not match the receiver's document. | Key does not match the document. |
PZK300 | 404 | Pix key not found. | Key not found in DICT. |
PZK301 | 404 | QR Code not found. | QR not found. |
PZK310 | 410 | This QR Code has expired or was removed by the receiving financial institution. | Request a new QR. |
PZK400 | 403 | Pix key lookup not enabled for the user. | Not enabled; contact support. |
PZK401 | 403 | QR Code reading not enabled for the user. | Not enabled. |
PZK600 | 400 | Invalid Pix key. Formats: CPF, CNPJ, email, phone (+55...) or random (UUID). | Fix the format. |
PZK601 | 400 | Invalid or malformed QR Code. | QR could not be read. |
Query / Receipt / 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 | An operation with this identifier already exists. Check the provided clientReference. | Duplicated clientReference; use another one or query the operation. |
PZC310 | 404 | Transaction not found. | Not located for your account. |
PZC320 | 422 | Transaction not yet processed. | Receipt unavailable while pending. |
PZC321 | 422 | Receipt unavailable: transaction cancelled without a document. | Cancelled transaction without receipt. |
PZI103 | 500 | Missing internal data to complete the operation. | 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 | Infraction already closed. | The infraction no longer accepts actions; query the current status. |
PZK212 | 409 | Defense already submitted. | A defense already exists for this infraction; query GET /v1/user/infractions/:id/defenses. |
Callback resend
Three routes resend callbacks, each with its own codes.
POST /v1/user/callbacks/resend/webhook/:webhookId
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZW300 | 404 | Webhook not found, inactive, or does not belong to the user | Check webhookId and whether the webhook is active on the account. |
PZW310 | 404 | No failed callback found for the webhook | There is no failed delivery to resend on this webhook. |
POST /v1/user/callbacks/resend
Bulk resend, by filters.
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZG404 | 404 | No transaction found for the criteria provided | No transaction matches the window and filters sent; review the criteria. |
POST /v1/user/callbacks/resend/:transactionId
Resend for a single transaction.
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZG404 | 404 | Transaction not found or has no callback configured | Check transactionId and whether a callback is configured for it. |
All three routes return PZG422 when the resend limit is reached. That code is in the generic table.
Financial institution
They appear on routes that query the financial institution in real time.
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZI101 | 500 | Operation not supported for this financial institution. | The receiver institution does not support the operation. Do not retry; use another key or another payment method. |
PZI110 | 424 | Communication error with the financial institution. | Try again. |
PZI111 | 424 | The financial institution took too long to respond. Try again. | Timeout; on creation (deposit, Pix payment, transfer), query the state via clientReference before recreating. |
PZF500 | 424 | Financial institution temporarily unavailable. Try again shortly. | Retry after retryAfterSeconds. |
Generic
| Code | HTTP | Message | What to do |
|---|---|---|---|
PZG404 | 404 | Resource not found. | Resource does not exist. |
PZG409 | 409 | The request conflicts with the current state of the resource. | Query the state before retrying. |
PZG410 | 410 | This resource is no longer available. | Resource expired or removed. |
PZG422 | 422 | Could not process the request. | Business rule; fix as per the message. |
PZG423 | 422 | The amount exceeds the allowed limit for this operation. | Reduce the amount or review your limits. |
PZG429 | 429 | Too many requests in a short period. Try again shortly. | Wait for retryAfterSeconds. |