# Error codes (/en/docs/pix-processamento/error-codes) 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-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 [#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 [#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 [#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 [#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 [#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 [#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) [#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 [#callback-resend] Three routes resend callbacks, each with its own codes. ### `POST /v1/user/callbacks/resend/webhook/:webhookId` [#post-v1usercallbacksresendwebhookwebhookid] | 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` [#post-v1usercallbacksresend] 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` [#post-v1usercallbacksresendtransactionid] 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 [#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 [#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`. |