Learn what each API rejection means and when it is worth repeating the call.
Every rejection comes in this format:
{ " message " : "Saldo insuficiente para este saque." , " code " : "WITHDRAW_INSUFFICIENT_BALANCE" , " details " : { " available " : 12500 , " required " : 20250 } } Field Description messageText 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. codeStable code, which does not change without a new version. It is what your system uses to decide what to do. detailsContext for the rejection, when there is any. It may not come.
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.
Status What to do 400, 404, 409Do not repeat without fixing the request: the same call gets the same rejection. 403, 422Do 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). 401Do not repeat in a loop. Generate a new token or fix the credential. 412Repeat only after completing the missing step, indicated by the code. PAYMENT_CREATION_IN_FLIGHT resolves in a moment. 429Repeat after the time in Retry-After. 502The operation may have happened. See below. 503Repeat after waiting. Nothing was done. 500, 504, timeoutRepeat with increasing waits. If the operation moves money, follow the 502 rules.
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 . Credential rejections apply to all of them.
codeHTTP When AUTH_TOO_MANY_REQUESTS429 The request limit was exceeded. Wait for the Retry-After. RATE_LIMIT_UNAVAILABLE503 The request limit control is down. Nothing was done. REQUEST_INTEGER_OUT_OF_RANGE400 A number in the request is outside the accepted range. REQUEST_NOT_ALLOWED405 The route does not accept this HTTP method. REQUEST_NUL_BYTE400 The request has a null character. REQUEST_PAYLOAD_TOO_LARGE413 The body is larger than the accepted size. REQUEST_UNKNOWN_QUERY_PARAM400 The route does not know one of the query parameters. SCHEMA_INVALID400 A field or parameter is missing or has an invalid value. details points to which one. SCHEMA_MALFORMED_BODY400 The body is not valid JSON. SYSTEM_INTERNAL_ERROR500 PayZu internal error.
They apply to every route. More details in Credential rejections .
codeHTTP When JWT_INVALID_AUTH_FORMAT401 The Authorization header is missing, or the scheme is neither Bearer nor Basic. TOKEN_EXPIRED401 The credential had an expiration date, and it has passed. TOKEN_HOLDER_BLOCKED403 The account holder is blocked. TOKEN_INVALID401 Wrong, nonexistent or revoked credential, or expired or tampered token. TOKEN_INVALID_AUTH_FORMAT401 The Basic value does not decode to client_id:client_secret. TOKEN_IP_NOT_ALLOWED403 The call came from an IP outside the credential's list. TOKEN_MISSING_SCOPE403 The credential does not have the route's scope. details.scope says which one is missing. TOKEN_UNSUPPORTED_GRANT_TYPE400 grant_type is missing or different from client_credentials.
codeHTTP When ACCOUNT_BLOCKED_BY_PROVIDER422 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_STAFF422 The account is held by support, until it is released. In a transfer, it can be the destination account. ACCOUNT_NOT_OPERABLE412 The account is not active and cannot move money. PROVIDER_CAPABILITY_NOT_SUPPORTED422 The account does not offer this operation. PROVIDER_NOT_PROVISIONED412 The account has not finished being opened yet. PROVIDER_OPERATION_UNAVAILABLE422 The operation is unavailable for the account at the moment. PROVIDER_REFUSED502 The bank refused the operation. See After a 502 . PROVIDER_UNAVAILABLE502 The bank did not respond in time, and the operation may have happened. See After a 502 .
codeHTTP When CALLBACK_SECRET_ALREADY_ISSUED409 The account already has a callback secret. To change it, use rotation. CALLBACK_SECRET_MISSING412 The operation carries callbackUrl, and the account does not have a callback secret yet. PAYMENT_ABOVE_MAXIMUM422 The amount is above the account's maximum charge (payment in the limits ). PAYMENT_AMOUNT_NOT_ABOVE_FEE422 The amount is not greater than the receiving fee. PAYMENT_BELOW_MINIMUM422 The amount is below the account's minimum charge. PAYMENT_CREATION_IN_FLIGHT412 A charge with the same externalRef is still being created. Repeat in a few seconds. PAYMENT_DISABLED403 Charges are disabled for the account. PAYMENT_EXTERNAL_REF_MISMATCH409 A charge with this externalRef already exists, and some data is different. The different fields come in details.fields. PAYMENT_INVALID_CURSOR400 The list cursor is not valid. Start again from the first page. PAYMENT_NOT_FOUND404 The charge does not exist or belongs to another account.
codeHTTP When REFUND_ABOVE_REMAINING422 The requested amount is above what remains to be returned on the charge or the deposit. REFUND_ABOVE_TICKET_MAX422 The amount is above the account's maximum per operation, which is the withdrawal one. REFUND_ALREADY_REFUNDED422 The charge or the deposit was already returned in full. REFUND_DISABLED403 Refunds are disabled for the account. REFUND_INFRACTION_OPEN422 There is a MED dispute open on the charge or the deposit. Wait for its result. REFUND_INSUFFICIENT_BALANCE422 The available balance does not cover the refund. REFUND_IN_FLIGHT422 A refund is already being processed. Wait for the result. REFUND_NOT_PAID422 The charge was not paid.
codeHTTP When QR_AMOUNT_DISAGREES422 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_MISMATCH422 The Pix copy-and-paste code sets an amount, and the amount sent is different. QR_AMOUNT_REQUIRED422 The Pix copy-and-paste code does not set an amount, and amount is missing. QR_CRC400 The Pix copy-and-paste code is corrupted. Copy it again. QR_MALFORMED400 The Pix copy-and-paste code is not in a valid format. QR_NOT_PIX400 The text sent is not a Pix copy-and-paste code. WITHDRAW_ABOVE_TICKET_MAX422 The amount is above the account's maximum withdrawal (withdraw in the limits ). WITHDRAW_BELOW_TICKET_MIN422 The amount is below the account's minimum withdrawal. WITHDRAW_DAILY_LIMIT422 The request would exceed the daily cap on Pix outflows (dailyWithdraw). WITHDRAW_DISABLED403 Withdrawals are disabled for the account. WITHDRAW_IDEMPOTENCY_KEY_REUSED409 The Idempotency-Key was already used in a request with other data. WITHDRAW_INSUFFICIENT_BALANCE422 The available balance does not cover the amount plus the fee. details carries available and required. WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE422 The bank does not cover the withdrawal at that moment, even with enough available. WITHDRAW_INVALID_IDEMPOTENCY_KEY400 The Idempotency-Key does not have 1 to 255 visible characters. WITHDRAW_INVALID_PIX_KEY400 CPF or CNPJ with a wrong check digit, or 11 digits that are neither a CPF nor a mobile number. WITHDRAW_NOT_FOUND404 The withdrawal does not exist or belongs to another account. WITHDRAW_PIX_KEY_REFUSED_BY_PROVIDER422 The bank refused the destination key. WITHDRAW_PIX_KEY_TYPE_MISMATCH400 pixKeyType does not match the key. details.inferred says the inferred type.WITHDRAW_UNRECOGNIZED_PIX_KEY422 The key type cannot be inferred.
codeHTTP When PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER502 The bank does not allow key lookups for this account. Contact support: repeating does not help. PIX_DEST_PIX_KEY404 The key does not exist in the DICT, the Pix key directory. Check the key. PIX_DEST_THROTTLED503 The bank's lookup limit was exceeded. Wait a little and repeat. PIX_DEST_UNAVAILABLE503 The lookup did not happen. Repeat in a moment.
codeHTTP When PIX_KEY_DEFAULT_CANNOT_BE_REMOVED422 It is the default key. Set another one as the default before deleting. PIX_KEY_DEFAULT_ON_PROVIDER422 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_HOLDER400 The CPF or CNPJ key is not the account holder's document. PIX_KEY_DUPLICATED409 The key is already registered on this account. PIX_KEY_NOT_FOUND404 The key does not exist, was already deleted or belongs to another account. PIX_KEY_ONLY_ACTIVE_CAN_BE_DEFAULT422 The key is not ACTIVE and cannot be the default. PIX_KEY_PROVIDER_REFUSED422 The bank refused the key. The reason comes in details.reason. PIX_KEY_RANDOM_KEY_NOT_ALLOWED400 Request for an EVP key with key. The random key is generated by the bank. PIX_KEY_REQUIRED400 A type other than EVP without key. PIX_KEY_TYPE_NOT_SUPPORTED_BY_PROVIDER422 A key type the account does not create: CPF, EMAIL or PHONE.
codeHTTP When TRANSFER_ABOVE_TICKET_MAX422 The amount is above the account's maximum transfer (internalTransfer in the limits ). TRANSFER_AMBIGUOUS_DESTINATION422 The key is active in more than one account. TRANSFER_BELOW_TICKET_MIN422 The amount is below the account's minimum transfer. TRANSFER_DAILY_LIMIT422 The request would exceed the daily cap on transfers (dailyInternalTransfer). TRANSFER_DESTINATION404 No PayZu account has this key active. TRANSFER_DESTINATION_NOT_ACTIVE422 The destination account is not active. TRANSFER_DIFFERENT_PROVIDER422 The destination account operates at another bank. Use a withdrawal. TRANSFER_DISABLED403 Transfers between accounts are disabled for the account. TRANSFER_IDEMPOTENCY_KEY_REUSED409 The Idempotency-Key was already used with another amount or destination. TRANSFER_INSUFFICIENT_BALANCE422 The available balance does not cover the amount plus the fee. details carries available and required. TRANSFER_INVALID_IDEMPOTENCY_KEY400 The Idempotency-Key does not have 1 to 255 visible characters. TRANSFER_MAIN_ACCOUNT_DESTINATION422 The key belongs to PayZu's main account, which does not receive transfers. To pay PayZu, use a charge. TRANSFER_NOT_FOUND404 The transfer does not exist or belongs to another account. TRANSFER_NOT_SUPPORTED422 Your account does not make transfers between accounts. TRANSFER_NO_ORIGIN_KEY422 Your account has no active Pix key to send the transfer. TRANSFER_SAME_ACCOUNT422 The key belongs to your own account.
codeHTTP When DEPOSIT_NOT_FOUND404 The deposit does not exist or belongs to another account. RECEIPT_MISSING_END_TO_END422 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_SETTLED422 The operation has not been completed yet. The receipt is only available afterwards.
codeHTTP When INFRACTION_NOT_FOUND404 The dispute does not exist or belongs to another account.
codeHTTP When WEBHOOK_DUPLICATED_URL409 Another endpoint on the account already uses this URL. WEBHOOK_HAS_DELIVERIES409 The endpoint already had a delivery and cannot be deleted. To stop receiving, send isActive: false. WEBHOOK_NOT_FOUND404 The endpoint does not exist or belongs to another account.
