AI resources
Main statuses and possible errors
See below the main statuses of a transaction and the possible request errors.
After the successful creation of the payout, transactions are generated, which correspond to the transactions sent in the body of the request. When you create a transaction, or when you query information related to it, the responses will return the fields that will allow you to know the status it is in.
status: this field will provide information about the current processing state.status_detail: this field belongs to each transaction and provides information about the reasons or details that resulted in that status. It is returned astransactions[].status_detailin a transaction list and asstatus_detailin an individual transaction response.
See below all the statuses that a transaction can go through during its processing.
status | status_detail | Description |
approved | - | A transaction was created, but has not yet been processed. It is an intermediate status. |
approved | partially_refunded | The transaction was partially refunded by the destination bank. |
canceled | - | A scheduled transaction was canceled using the Cancel a transactionPUT endpoint. |
created | - | The transaction was created. |
error | failed | When an error occurs in the transaction process and the amount cannot be credited to the destination account. Check here for more information about the returned messages. |
error | invalid_chave_pix | The Pix key sent is invalid, belongs to a different account than expected, or is on the deny list. |
error | missing_pix_alias | The Pix key was resolved, but the returned account information is incomplete for the transfer to proceed. |
error | downstream_service_unavailable | A transient failure occurred while resolving the Pix key with the recipient lookup service. This indicates instability, not a business rejection. |
error | incomplete_recipient_data | The Pix key was resolved successfully, but the recipient's bank account data is incomplete. |
error | account_finder_internal_error | An unexpected internal error occurred while resolving the Pix key. |
error | processing_cancelled | The Pix key resolution could not be completed before the request was canceled. |
processed | approved | The transaction processing was successful. |
refunded | refunded | The transaction was fully refunded by the destination bank. |
rejected | by_bank | The transaction was rejected by the destination bank. Execute the request again. |
rejected | by_provider | The transaction was rejected by the provider. Execute the request again. |
rejected | high_risk | The transaction is rejected due to fraud risk. Execute the request again. |
rejected | insufficient_funds | The transaction was rejected due to insufficient funds in the origin account. Execute the request again. |
rejected | other_reason | The transaction was rejected by default due to internal issues during processing. Execute the request again. |
rejected | review_manual | The transaction is rejected and sent for fraud prevention analysis. Execute the request again. |
success | accredited | The transaction is credited to the destination account. |
success | in_progress | The transaction crediting is in process, it is not yet in the destination account. |
transaction_in_process | pending_authorized | The transaction is in progress, with final status pending and awaiting authorization. |
transaction_in_process | pending_bank | The destination bank did not respond, therefore, the transaction is pending a final state. |
Transaction error messages
When a transaction has status=error and status_detail=failed, the response contains a user-friendly message describing the cause of the error. For Pix transactions, status_detail can return the specific values shown at the end of the table.
status_detail | Message |
failed | The payer's account does not have sufficient funds to complete this transaction. Please verify the account balance and try again. |
failed | Unable to process the transaction. An error occurred while reserving funds. Please try again later or contact support. |
failed | TED account not found or inactive. Please verify the account information and try again. |
failed | Unable to process the transaction. An error occurred while processing payment data. Please try again later or contact support. |
failed | Transaction was rejected. Please verify the transaction details and try again. If the issue persists, contact support. |
failed | Unable to process the transaction. An internal error occurred. Please try again later or contact support. |
failed | Resource not found. Please verify the transaction details and try again. |
failed | Invalid date format. Please verify the date fields in your request. |
failed | Unable to retrieve bank information. Please verify the bank account details and try again. |
failed | Invalid user information. Please verify the user IDs in your request. |
failed | We're temporarily unable to display the status of this transfer. This does not mean the transfer failed. Please refresh in a few moments or contact support. |
failed | Service temporarily unavailable. Please try again later. |
failed | An unexpected error occurred. Please contact support for assistance. |
invalid_chave_pix | The Pix key is invalid or belongs to a different account. Please verify the Pix key and try again. |
missing_pix_alias | We couldn't retrieve complete account information for this Pix key. Please verify the Pix key and try again. |
account_finder_internal_error | An unexpected error occurred while validating the Pix key. Please try again later or contact support. |
downstream_service_unavailable | We couldn't retrieve the account information for this Pix key. Please try again later. |
processing_cancelled | We couldn't finish validating this Pix key in time. Please try again. |
Here you can find the possible errors that may occur when making a payout request, along with their descriptions and possible solutions.
The following errors related to the destination account data or type may also occur:
| Error Type | Status | Code | Description and possible solutions |
| Request error | 400 | invalid_payout_id | The value sent in the payout_id path parameter is invalid or does not identify an existing payout. Verify the identifier and try again. |
| Request error | 400 | invalid_transaction_id | The value sent in the transaction_id path parameter is invalid or does not identify an existing transaction. Verify the identifier and try again. |
| Request error | 400 | invalid_signature | The signature sent in the X-signature header is invalid or does not match the encrypted request body. Verify that the secret used to generate the signature is correct and that the submitted body is the same one used to generate it. For more information, see Security encryption. |
| Request error | 400 | idempotency_key_required | The required X-Idempotency-Key header was not sent. Include it with a unique value and try the request again. |
| Request error | 400 | invalid_account | The account object was sent without any identification field. Send at least an email (Mercado Pago account) or a number/bank_id (bank account). |
| Request error | 400 | invalid_account_type | The account_type field was sent with a value outside the accepted set. The accepted values are checking_account or savings. |
| Request error | 400 | invalid_account_type_for_site | The value savings was sent for account_type outside Brazil. |
| Request error | 401 | invalid_token | The value sent as Access Token is incorrect. Please check and try again with the correct value. |
| Request error | 403 | forbidden | No permission to access the resource. Check if the Access Token sent has the necessary permissions. |
| Request error | 404 | not_found | The requested resource was not found or the value sent for its identification does not exist. Validate the information sent in the parameters and try the request again. |
| Request error | 412 | precondition_failed | The status of the transaction does not allow its cancellation. Only transactions with status=pending or in_process can be canceled. |
| API error | 500 | internal_server_error | An unexpected error occurred on the server. Try the request again. If the issue persists, contact support. |
| API error | 502 | bad_gateway | An error occurred in the integration with an external service. Try the request again. If the issue persists, contact support. |