AI resources

Possible errors

During integration with Checkout Pro through the Orders API, errors may occur in requests to the different endpoints. Below are the error codes organized by endpoint, along with their cause and solution.

Errors creating an order

HTTP Code	Error code	Message	Cause and solution
`400`	`empty_required_header`	`Missing HTTP header: X-Idempotency-Key`	Include the `X-Idempotency-Key` header with a unique UUID in the request.
`400`	`invalid_idempotency_key_length`	`X-Idempotency-Key length exceeds 128 characters`	Reduce the idempotency key length to a maximum of 128 characters.
`400`	`required_properties`	`required property 'email' is missing`	Verify that all required fields are present in the request body.
`400`	`invalid_total_amount`	`total_amount is not equivalent to sum...`	Verify that the `total_amount` value equals the sum of the `unit_price` multiplied by the `quantity` of all items in the order.
`400`	`maximum_items`	`maximum 1 items required, but found 2`	Send only 1 transaction per order in the request.
`400`	`unsupported_properties`	`An unsupported property was sent. Check the message returned in the error details.`	An unsupported field was included in the request body. Check the `details` field in the error response to identify which property caused the issue, remove it, and retry.
`400`	`minimum_properties`	`The minimum number of properties required was not sent. Check the error details`	The request did not include the minimum number of required properties. Check the `details` field in the error response to identify which object or sub-object is missing mandatory fields, and retry with the complete payload.
`400`	`idempotency_validation_failed`	`Validation fail. Please try submitting the request again`	The server failed to validate the idempotency key on its end. This is a transient server-side error. Generate a new `X-Idempotency-Key` and resubmit the request.
`400`	`property_value`	`invalid value 'X', expected one of: online, point, qr`	Use the value `online` in the `type` field for Checkout Pro integrations.
`400`	`property_type`	`expected string, but got number`	Check the data types for each field. See the API reference for more details.
`400`	`json_syntax_error`	`An incorrect JSON was sent`	Validate the JSON syntax in the request body.
`400`	`invalid_email_for_sandbox`	`Email must contain '@testuser.com'`	Use email addresses with the `@testuser.com` domain in the sandbox environment.
`409`	`idempotency_key_already_used`	`X-Idempotency-Key already used...`	Generate a new idempotency key. The key sent was already used in a previous request.
`423`	`resource_locked`	`Idempotency Key Locked...`	The resource is being processed with the same idempotency key. Wait a few seconds and try again.
`500`	`internal_error`	`Some error occurred on our side`	Internal server error. Retry the request later.

Errors checking an order

HTTP Code	Error code	Message	Cause and solution
`400`	`invalid_path_param`	`Path param order id is invalid`	Verify that the order ID has the correct format (ULID).
`404`	`order_not_found`	`order not found`	Verify that the Access Token corresponds to the order creator.

Errors canceling an order

HTTP Code	Error code	Message	Cause and solution
`400`	`invalid_path_param`	`Path param order id is invalid`	Verify that the order ID has the correct format (ULID).
`400`	`empty_required_header`	`Missing HTTP header: X-Idempotency-Key`	Include the `X-Idempotency-Key` header with a unique UUID.
`404`	`order_not_found`	`order not found`	Verify that the Access Token corresponds to the order creator.
`409`	`cannot_cancel_order`	`Only orders with status 'action_required' or 'created'...`	The order is in an incompatible state for cancellation. Only orders with status `created` or `action_required` can be canceled.
`409`	`order_already_cancelled`	`The order has already been canceled`	The order has already been canceled. There is no need to send the request again.

Errors refunding an order

HTTP Code	Error code	Message	Cause and solution
`400`	`refund_amount_exceeds`	`Refund amount exceeds the available amount`	The refund amount exceeds the available amount. Check the available amount for refund.
`400`	`order_refund_already_in_process`	`There is already a full refund request in process`	There is already a full refund request in process. Wait for it to complete before submitting a new request.
`404`	`transaction_not_found`	`Transaction not found`	Verify that the transaction ID is correct.
`409`	`cannot_refund_order`	`Cannot refund order...`	The order must be in `processed` status for a refund to be requested.

For more information on how to submit requests, requirements, and necessary validations, see our API referenceAPI.

PreviousOrder statusCheck the main statuses that an order may have when querying for its information.

NextIntroductionGet to know Mercado Pago MCP Server