AI resources
Possible API errors
Check the possible errors returned by the Orders API and how to manage them. Errors that can occur in more than one operation are grouped as common errors, while the remaining errors are organized by endpoint.
These errors can occur in more than one Orders API endpoint.
| Error Type | Status | Code | Description and possible solutions |
| Request Error | 400 | json_syntax_error | Ensure that the request has a valid JSON structure, with appropriate keys and values. |
| Request Error | 400 | required_properties | Some mandatory properties are missing. Check the request and ensure all required properties are included according to the API documentation. |
| Request Error | 400 | unsupported_properties | Some provided properties are not supported by the API. Review the request and remove or correct unsupported properties. |
| Request Error | 400 | minimum_properties | The minimum number of required properties has not been met. Add the necessary properties to complete the request. |
| Request Error | 400 | property_type | The type of the provided property is invalid. Ensure that the value sent in the request matches the expected type. |
| Request Error | 400 | property_value | The value of the provided property is invalid. Check the sent value and make adjustments to match the allowed values. |
| Request Error | 400 | maximum_items | The maximum number of allowed items has been exceeded. Reduce the number of items sent so that it does not exceed the permitted maximum. |
| Request Error | 400 | minimum_items | The minimum number of required items has not been met. Add more items to the request to meet the API requirements. |
| Request Error | 400 | invalid_path_param | Check if the ID provided as a parameter is valid. |
| Request Error | 400 | invalid_properties | Some provided properties are invalid or malformed. Review the submitted properties and verify if they comply with the API specifications. |
| Request Error | 400 | empty_required_header | One or more mandatory headers are empty. Check the request and ensure that all required headers are present and properly filled out. |
| Request Error | 400 | invalid_idempotency_key_length | The value sent in the X-Idempotency-Key header exceeded the allowed size. The header accepts values between 1 and 128 characters. |
| Request Error | 400 | invalid_order_mode_for_operation | The reported mode is not valid for this operation. Verify if you are using the correct mode according to the desired operation. |
| Request Error | 400 | invalid_transaction_id | The transaction ID is invalid. Ensure that the ID is correct. |
| Request Error | 400 | invalid_total_amount | The value provided in total_amount does not match the sum of the values in transactions.payments.amount for all transactions. Check that the values are correct and that the sum of the transaction values matches the provided total_amount. |
| Request Error | 401 | 401 | The value sent as Access Token is incorrect. Please check and try again with the correct value. |
| Request Error | 401 | invalid_credentials | There is no support for test credentialsUnique access keys that we use to identify an integration in your account, linked to your application. For more information, see the link below.Credentials. Use test users with production credentials for the sandbox environment and your production credentials for the production environment. |
| Request Error | 402 | failed | There was an error processing one of the transactions. Check the returned message for more information. |
| Request Error | 403 | forbidden | The application does not have permission to access this resource. Please check that the Access Token used has the necessary permissions and scopes for this operation. |
| Request Error | 403 | PA_UNAUTHORIZED_RESULT_FROM_POLICIES | The account is blocked and its API keys have been revoked. At least one policy evaluated by the Policy Agent returned an UNAUTHORIZED result. Contact Mercado Pago Support to unblock your account. |
| Request Error | 404 | order_not_found | The order was not found. Check if the provided ID is correct. |
| Request Error | 409 | idempotency_key_already_used | The provided X-Idempotency-Key has already been used. Each idempotency key must be unique to ensure that the operation is performed only once. Use a new key for the next request. |
| Request Error | 429 | usage_quota_exceeded | Request limit per client reached. Read the Retry-After header from the response and wait the indicated number of seconds before retrying. For greater resilience, implement exponential backoff with jitter, that is, increase the wait time with each new attempt and add a random variation to avoid simultaneous retransmission of multiple requests. |
| API Error | 500 | idempotency_validation_failed | An internal server error occurred. Try resending the request with a new and unique idempotency key to avoid conflicts. If the problem persists, contact Support and provide the x-request-id along with more details about the operation performed. |
| API Error | 500 | internal_error | An internal server error occurred. Please try again later. If the problem persists, contact Support and provide the x-request-id along with more details about the operation performed. |
Errors specific to the /v1/ordersPOST endpoint.
| Error Type | Status | Code | Description and possible solutions |
| Request Error | 400 | order_builder_without_transactions | There is no transaction associated with the order. Ensure to include at least one transaction for the creation of the order. |
| Request Error | 400 | invalid_order_type | The type of the order is invalid. Check if the type used is valid for the operation. |
| Request Error | 400 | invalid_email_for_sandbox | Email format is invalid for sandbox environment, must contains "@testuser.com". |
| Request Error | 400 | property_value | The domain provided in payer.email is not allowed. Use an email with a valid domain. |
| Request Error | 400 | property_value | The email provided in payer.email contains words that are not allowed. Review the value sent and use a valid email. |
| Request Error | 400 | property_value | The config.location.state_id value is not valid for the order site. Send a valid code in the documented format. |
| Request Error | 400 | property_value | The order-level expiration_time value is not a valid ISO 8601 duration. Send a duration in ISO 8601 format (for example, PT2H). |
| Request Error | 400 | property_value | The order-level expiration_time value exceeds 2920 hours. Send a duration of up to 2920 hours. |
| Request Error | 400 | order_invalid_sponsor_id | The order sponsor ID is invalid. Make sure the ID is correct. |
| Request Error | 400 | invalid_header_value | Caller ID (caller_id) not found. Make sure the ID is correct. |
| Request Error | 423 | resource_locked | The idempotency key is temporarily locked. Wait a moment and try to execute the request again. |
Errors specific to the /v1/ordersGET endpoint.
| Error Type | Status | Code | Description and possible solutions |
| Request Error | 400 | required_search_params | Required search parameters are missing. Include begin_date and end_date in the request. |
| Request Error | 400 | invalid_search_params | One or more search parameters are invalid. Check the response details and correct the date format, pagination, sorting, or filters. |
Error specific to the /v1/orders/{order_id}/transactionsPOST endpoint.
| Error Type | Status | Code | Description and possible solutions |
| Request Error | 400 | exceeded_number_of_transactions | An error occurred in the request. The Order accepts a maximum of one transaction. Remove the excess transactions. |
Errors specific to the /v1/orders/{order_id}/refundPOST endpoint.
| Error Type | Status | Code | Description and possible solutions |
| Request Error | 400 | refund_amount_exceeds | The refund amount requested is greater than the amount available for refund on the order. Check the amount available for refund and adjust the field so it does not exceed this limit. |
| Request Error | 404 | transaction_not_found | The transaction was not found. Check if the provided ID is correct. |
| Request Error | 409 | cannot_refund_order | Ensure that the order is in a status that allows for a refund to be made. |
| Request Error | 409 | order_already_refunded | The reported order has already been refunded. It is not possible to process a refund on an order that already has this status. |
| Request Error | 409 | order_refund_already_in_process | There is already a full refund request in process for the order in question. |
Errors specific to the /v1/orders/{order_id}/capturePOST endpoint.
| Error Type | Status | Code | Description and possible solutions |
| Request Error | 409 | cannot_capture_order | Check if the order's status allows capturing and whether it was created with the processing_mode field set to automatic. |
| Request Error | 409 | operation_not_supported | The requested operation is not supported. Check if the operation you are trying to perform is valid for the current context. |
Errors specific to the /v1/orders/{order_id}/cancelPOST endpoint.
| Error Type | Status | Code | Description and possible solutions |
| Request Error | 409 | cannot_cancel_order | Ensure that the order is in a status that allows cancellation. |
| Request Error | 409 | order_already_canceled | The reported order has already been canceled. It is not possible to perform operations on an order that is already canceled. |
For more information on how to submit the necessary requests, requirements and validations, see our API ReferenceAPI.