# Error codes (/en/docs/conta-digital/error-codes) Every rejection comes in this format: ```json { "message": "Saldo insuficiente para este saque.", "code": "WITHDRAW_INSUFFICIENT_BALANCE", "details": { "available": 12500, "required": 20250 } } ``` | Field | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `message` | Text in Portuguese, for display to the people who use your system. It can change at any time, so the tables on this page do not repeat it. | | `code` | Stable code, which does not change without a new version. It is what your system uses to decide what to do. | | `details` | Context for the rejection, when there is any. It may not come. | ## What comes in `details` [#what-comes-in-details] * `SCHEMA_INVALID`: the field with the problem, in the shape of the body. For example, `{ "customer": { "document": "Informe um CPF ou CNPJ válido." } }`. * `REQUEST_UNKNOWN_QUERY_PARAM`: `details.unknownParams` carries the query parameters the route does not know, and `details.accepted`, the ones it accepts. In the body, an unknown field is ignored. * `429`: `details.retryAfterSeconds`, the same number of seconds as the `Retry-After` header. * `PROVIDER_UNAVAILABLE` and `PROVIDER_REFUSED`: the status and the reason returned by the bank, in `details.status` and `details.reason`. `details.status` comes `null` when the bank did not respond. ## When to repeat [#when-to-repeat] | Status | What to do | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400`, `404`, `409` | Do not repeat without fixing the request: the same call gets the same rejection. | | `403`, `422` | Do not repeat as is. Some change with the account state: `RECEIPT_MISSING_END_TO_END` (try again in a few minutes), `REFUND_IN_FLIGHT` (wait for the result of the previous refund), `*_INSUFFICIENT_BALANCE` (after balance comes in), `*_DAILY_LIMIT` (the next day, Brasília time) and `TOKEN_HOLDER_BLOCKED` (when the block is lifted). | | `401` | Do not repeat in a loop. Generate a new token or fix the credential. | | `412` | Repeat only after completing the missing step, indicated by the `code`. `PAYMENT_CREATION_IN_FLIGHT` resolves in a moment. | | `429` | Repeat after the time in `Retry-After`. | | `502` | The operation may have happened. See below. | | `503` | Repeat after waiting. Nothing was done. | | `500`, `504`, timeout | Repeat with increasing waits. If the operation moves money, follow the `502` rules. | ### After a `502` [#after-a-502] `PROVIDER_UNAVAILABLE`, or `PROVIDER_REFUSED` with `details.status` `408` or `429`, means the bank did not give a final answer and the operation may have happened. To repeat without duplicating: * **Withdrawal, Pix copy-and-paste payment and transfer:** repeat with the same `Idempotency-Key`, or look the operation up before requesting again. * **Charge:** repeat with the same `externalRef`. * **Refund and deposit return:** look the operation up before requesting again. These routes do not accept `Idempotency-Key`. Any other `PROVIDER_REFUSED` is a refusal from the bank: do not repeat. Each route lists its own rejections in the [API reference](/docs/conta-digital/endpoints). Credential rejections apply to all of them. ## Requests and request limit [#requests-and-request-limit] | `code` | HTTP | When | | ------------------------------ | ---- | --------------------------------------------------------------------------------------- | | `AUTH_TOO_MANY_REQUESTS` | 429 | The request limit was exceeded. Wait for the `Retry-After`. | | `RATE_LIMIT_UNAVAILABLE` | 503 | The request limit control is down. Nothing was done. | | `REQUEST_INTEGER_OUT_OF_RANGE` | 400 | A number in the request is outside the accepted range. | | `REQUEST_NOT_ALLOWED` | 405 | The route does not accept this HTTP method. | | `REQUEST_NUL_BYTE` | 400 | The request has a null character. | | `REQUEST_PAYLOAD_TOO_LARGE` | 413 | The body is larger than the accepted size. | | `REQUEST_UNKNOWN_QUERY_PARAM` | 400 | The route does not know one of the query parameters. | | `SCHEMA_INVALID` | 400 | A field or parameter is missing or has an invalid value. `details` points to which one. | | `SCHEMA_MALFORMED_BODY` | 400 | The body is not valid JSON. | | `SYSTEM_INTERNAL_ERROR` | 500 | PayZu internal error. | ## Credential [#credential] They apply to every route. More details in [Credential rejections](/docs/conta-digital/authentication#credential-rejections). | `code` | HTTP | When | | ------------------------------ | ---- | ------------------------------------------------------------------------------------------ | | `JWT_INVALID_AUTH_FORMAT` | 401 | The `Authorization` header is missing, or the scheme is neither `Bearer` nor `Basic`. | | `TOKEN_EXPIRED` | 401 | The credential had an expiration date, and it has passed. | | `TOKEN_HOLDER_BLOCKED` | 403 | The account holder is blocked. | | `TOKEN_INVALID` | 401 | Wrong, nonexistent or revoked credential, or expired or tampered token. | | `TOKEN_INVALID_AUTH_FORMAT` | 401 | The `Basic` value does not decode to `client_id:client_secret`. | | `TOKEN_IP_NOT_ALLOWED` | 403 | The call came from an IP outside the credential's list. | | `TOKEN_MISSING_SCOPE` | 403 | The credential does not have the route's scope. `details.scope` says which one is missing. | | `TOKEN_UNSUPPORTED_GRANT_TYPE` | 400 | `grant_type` is missing or different from `client_credentials`. | ## Account and bank [#account-and-bank] | `code` | HTTP | When | | ----------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------- | | `ACCOUNT_BLOCKED_BY_PROVIDER` | 422 | The bank blocked this operation on the account, until it is unblocked. In a transfer, it can be the inflow on the destination account. | | `ACCOUNT_HELD_BY_STAFF` | 422 | The account is held by support, until it is released. In a transfer, it can be the destination account. | | `ACCOUNT_NOT_OPERABLE` | 412 | The account is not active and cannot move money. | | `PROVIDER_CAPABILITY_NOT_SUPPORTED` | 422 | The account does not offer this operation. | | `PROVIDER_NOT_PROVISIONED` | 412 | The account has not finished being opened yet. | | `PROVIDER_OPERATION_UNAVAILABLE` | 422 | The operation is unavailable for the account at the moment. | | `PROVIDER_REFUSED` | 502 | The bank refused the operation. See [After a `502`](#after-a-502). | | `PROVIDER_UNAVAILABLE` | 502 | The bank did not respond in time, and the operation may have happened. See [After a `502`](#after-a-502). | ## Charge and callback [#charge-and-callback] | `code` | HTTP | When | | -------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------- | | `CALLBACK_SECRET_ALREADY_ISSUED` | 409 | The account already has a callback secret. To change it, use rotation. | | `CALLBACK_SECRET_MISSING` | 412 | The operation carries `callbackUrl`, and the account does not have a callback secret yet. | | `PAYMENT_ABOVE_MAXIMUM` | 422 | The amount is above the account's maximum charge (`payment` in the [limits](/docs/conta-digital/statement#limits)). | | `PAYMENT_AMOUNT_NOT_ABOVE_FEE` | 422 | The amount is not greater than the receiving fee. | | `PAYMENT_BELOW_MINIMUM` | 422 | The amount is below the account's minimum charge. | | `PAYMENT_CREATION_IN_FLIGHT` | 412 | A charge with the same `externalRef` is still being created. Repeat in a few seconds. | | `PAYMENT_DISABLED` | 403 | Charges are disabled for the account. | | `PAYMENT_EXTERNAL_REF_MISMATCH` | 409 | A charge with this `externalRef` already exists, and some data is different. The different fields come in `details.fields`. | | `PAYMENT_INVALID_CURSOR` | 400 | The list `cursor` is not valid. Start again from the first page. | | `PAYMENT_NOT_FOUND` | 404 | The charge does not exist or belongs to another account. | ## Refund and return [#refund-and-return] | `code` | HTTP | When | | ----------------------------- | ---- | --------------------------------------------------------------------------------------- | | `REFUND_ABOVE_REMAINING` | 422 | The requested amount is above what remains to be returned on the charge or the deposit. | | `REFUND_ABOVE_TICKET_MAX` | 422 | The amount is above the account's maximum per operation, which is the withdrawal one. | | `REFUND_ALREADY_REFUNDED` | 422 | The charge or the deposit was already returned in full. | | `REFUND_DISABLED` | 403 | Refunds are disabled for the account. | | `REFUND_INFRACTION_OPEN` | 422 | There is a MED dispute open on the charge or the deposit. Wait for its result. | | `REFUND_INSUFFICIENT_BALANCE` | 422 | The available balance does not cover the refund. | | `REFUND_IN_FLIGHT` | 422 | A refund is already being processed. Wait for the result. | | `REFUND_NOT_PAID` | 422 | The charge was not paid. | ## Withdrawal and Pix copy-and-paste payment [#withdrawal-and-pix-copy-and-paste-payment] | `code` | HTTP | When | | ---------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `QR_AMOUNT_DISAGREES` | 422 | The amount printed in the Pix copy-and-paste code differs from what the bank reports for it. Confirm the amount with whoever issued the charge. | | `QR_AMOUNT_MISMATCH` | 422 | The Pix copy-and-paste code sets an amount, and the `amount` sent is different. | | `QR_AMOUNT_REQUIRED` | 422 | The Pix copy-and-paste code does not set an amount, and `amount` is missing. | | `QR_CRC` | 400 | The Pix copy-and-paste code is corrupted. Copy it again. | | `QR_MALFORMED` | 400 | The Pix copy-and-paste code is not in a valid format. | | `QR_NOT_PIX` | 400 | The text sent is not a Pix copy-and-paste code. | | `WITHDRAW_ABOVE_TICKET_MAX` | 422 | The amount is above the account's maximum withdrawal (`withdraw` in the [limits](/docs/conta-digital/statement#limits)). | | `WITHDRAW_BELOW_TICKET_MIN` | 422 | The amount is below the account's minimum withdrawal. | | `WITHDRAW_DAILY_LIMIT` | 422 | The request would exceed the daily cap on Pix outflows (`dailyWithdraw`). | | `WITHDRAW_DISABLED` | 403 | Withdrawals are disabled for the account. | | `WITHDRAW_IDEMPOTENCY_KEY_REUSED` | 409 | The `Idempotency-Key` was already used in a request with other data. | | `WITHDRAW_INSUFFICIENT_BALANCE` | 422 | The available balance does not cover the amount plus the fee. `details` carries `available` and `required`. | | `WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE` | 422 | The bank does not cover the withdrawal at that moment, even with enough `available`. | | `WITHDRAW_INVALID_IDEMPOTENCY_KEY` | 400 | The `Idempotency-Key` does not have 1 to 255 visible characters. | | `WITHDRAW_INVALID_PIX_KEY` | 400 | CPF or CNPJ with a wrong check digit, or 11 digits that are neither a CPF nor a mobile number. | | `WITHDRAW_NOT_FOUND` | 404 | The withdrawal does not exist or belongs to another account. | | `WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER` | 422 | The bank refused the destination key. | | `WITHDRAW_PIX_KEY_TYPE_MISMATCH` | 400 | `pixKeyType` does not match the key. `details.inferred` says the inferred type. | | `WITHDRAW_UNRECOGNIZED_PIX_KEY` | 422 | The key type cannot be inferred. | ## Recipient lookup [#recipient-lookup] | `code` | HTTP | When | | ------------------------------------- | ---- | ----------------------------------------------------------------------------------------------- | | `PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER` | 502 | The bank does not allow key lookups for this account. Contact support: repeating does not help. | | `PIX_DEST_PIX_KEY` | 404 | The key does not exist in the DICT, the Pix key directory. Check the key. | | `PIX_DEST_THROTTLED` | 503 | The bank's lookup limit was exceeded. Wait a little and repeat. | | `PIX_DEST_UNAVAILABLE` | 503 | The lookup did not happen. Repeat in a moment. | ## Pix keys [#pix-keys] | `code` | HTTP | When | | ---------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------- | | `PIX_KEY_DEFAULT_CANNOT_BE_REMOVED` | 422 | It is the default key. Set another one as the default before deleting. | | `PIX_KEY_DEFAULT_ON_PROVIDER` | 422 | The key is the account's default, even if the list did not show that yet. Set another one as the default before deleting. | | `PIX_KEY_DOCUMENT_NOT_HOLDER` | 400 | The CPF or CNPJ key is not the account holder's document. | | `PIX_KEY_DUPLICATED` | 409 | The key is already registered on this account. | | `PIX_KEY_NOT_FOUND` | 404 | The key does not exist, was already deleted or belongs to another account. | | `PIX_KEY_ONLY_ACTIVE_CAN_BE_DEFAULT` | 422 | The key is not `ACTIVE` and cannot be the default. | | `PIX_KEY_PROVIDER_REFUSED` | 422 | The bank refused the key. The reason comes in `details.reason`. | | `PIX_KEY_RANDOM_KEY_NOT_ALLOWED` | 400 | Request for an `EVP` key with `key`. The random key is generated by the bank. | | `PIX_KEY_REQUIRED` | 400 | A type other than `EVP` without `key`. | | `PIX_KEY_TYPE_NOT_SUPPORTED_BY_PROVIDER` | 422 | A key type the account does not create: `CPF`, `EMAIL` or `PHONE`. | ## Transfer between accounts [#transfer-between-accounts] | `code` | HTTP | When | | ----------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ | | `TRANSFER_ABOVE_TICKET_MAX` | 422 | The amount is above the account's maximum transfer (`internalTransfer` in the [limits](/docs/conta-digital/statement#limits)). | | `TRANSFER_AMBIGUOUS_DESTINATION` | 422 | The key is active in more than one account. | | `TRANSFER_BELOW_TICKET_MIN` | 422 | The amount is below the account's minimum transfer. | | `TRANSFER_DAILY_LIMIT` | 422 | The request would exceed the daily cap on transfers (`dailyInternalTransfer`). | | `TRANSFER_DESTINATION` | 404 | No PayZu account has this key active. | | `TRANSFER_DESTINATION_NOT_ACTIVE` | 422 | The destination account is not active. | | `TRANSFER_DIFFERENT_PROVIDER` | 422 | The destination account operates at another bank. Use a withdrawal. | | `TRANSFER_DISABLED` | 403 | Transfers between accounts are disabled for the account. | | `TRANSFER_IDEMPOTENCY_KEY_REUSED` | 409 | The `Idempotency-Key` was already used with another amount or destination. | | `TRANSFER_INSUFFICIENT_BALANCE` | 422 | The available balance does not cover the amount plus the fee. `details` carries `available` and `required`. | | `TRANSFER_INVALID_IDEMPOTENCY_KEY` | 400 | The `Idempotency-Key` does not have 1 to 255 visible characters. | | `TRANSFER_MAIN_ACCOUNT_DESTINATION` | 422 | The key belongs to PayZu's main account, which does not receive transfers. To pay PayZu, use a charge. | | `TRANSFER_NOT_FOUND` | 404 | The transfer does not exist or belongs to another account. | | `TRANSFER_NOT_SUPPORTED` | 422 | Your account does not make transfers between accounts. | | `TRANSFER_NO_ORIGIN_KEY` | 422 | Your account has no active Pix key to send the transfer. | | `TRANSFER_SAME_ACCOUNT` | 422 | The key belongs to your own account. | ## Deposit and receipt [#deposit-and-receipt] | `code` | HTTP | When | | ---------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------- | | `DEPOSIT_NOT_FOUND` | 404 | The deposit does not exist or belongs to another account. | | `RECEIPT_MISSING_END_TO_END` | 422 | The operation does not have an end-to-end ID yet, and without it there is no receipt. Try again in a few minutes. | | `RECEIPT_NOT_SETTLED` | 422 | The operation has not been completed yet. The receipt is only available afterwards. | ## Dispute [#dispute] | `code` | HTTP | When | | ---------------------- | ---- | --------------------------------------------------------- | | `INFRACTION_NOT_FOUND` | 404 | The dispute does not exist or belongs to another account. | ## Webhooks [#webhooks] | `code` | HTTP | When | | ------------------------ | ---- | ----------------------------------------------------------------------------------------------------- | | `WEBHOOK_DUPLICATED_URL` | 409 | Another endpoint on the account already uses this URL. | | `WEBHOOK_HAS_DELIVERIES` | 409 | The endpoint already had a delivery and cannot be deleted. To stop receiving, send `isActive: false`. | | `WEBHOOK_NOT_FOUND` | 404 | The endpoint does not exist or belongs to another account. |