AI resources
Refund errors
Below you will find all possible errors returned by the refund endpointAPI of the Orders API for QR Code and the recommended actions for each case.
Error codes
| HTTP | Error (error) | Description | Recommended action |
400 | empty_required_header | The X-Idempotency-Key header is required and was not sent. | Include the header in all refund requests. |
400 | invalid_path_param | The order_id sent in the path has an invalid format. It must start with the prefix ORD followed by 26 characters. | Verify and resend with a valid ID. |
400 | invalid_order_owner | It is not possible to process a refund for an order that was not created by the requester. | Verify that the Access Token belongs to the same user who created the order. |
400 | in_store_payment_refund_order | The maximum refund period has been exceeded. The limit is 360 days from the payment date. | No action possible; the refund period has already expired. |
400 | unsupported_partially_refunds | The order does not support partial refunds. | Check if the order is eligible for a partial refund before sending the body with transactions[]. |
400 | refund_amount_exceeds | The refund amount exceeds the available balance. | Verify that the amount sent is less than or equal to the transaction balance. |
401 | unauthorized | The Access Token sent is invalid or expired. | Verify and resend the request with the correct Access Token. |
401 | user_not_authorized | The user does not have permission to perform this action. | Verify that the Access Token belongs to the same user who created the order. |
403 | partial_refund_forbidden_with_tips | Partial refunds are not allowed on orders with tips. | Issue a full refund without sending the transactions[] array. |
404 | order_not_found | Order not found. | Verify that the order_id sent in the path is correct. |
404 | transaction_not_found | Transaction not found in the order. | Verify that the transactions[].id sent belongs to the specified order. |
409 | idempotency_key_already_used | The X-Idempotency-Key sent has already been used with a different body in the last 24 hours. | Send a new value for the header. |
409 | order_already_refunded | The order has already been fully refunded. | No action needed; the refund has already been completed. |
409 | cannot_refund_order | The current state of the order does not allow a refund. | Verify that the order has status: processed before requesting a refund. |
409 | refund_period_exceeded | The maximum refund period has been exceeded. | Refunds are accepted up to 360 days from the payment date. |
409 | action_not_allowed_for_current_state | The action is not allowed by the current payment status. | Check the status and status_detail of the order before attempting the refund. |
409 | refund_in_progress | A refund is already being processed for this order. | Wait a few minutes before trying again. |
409 | movement_operations_pending | The order has pending financial movements. | Wait a few minutes and retry the request. |
422 | payment_not_refundable | The payment cannot be refunded. | Check the payment conditions; some payment methods do not support refunds. |
422 | amount_not_refundable | The requested amount cannot be refunded. | Try a different amount or check the payment conditions. |
422 | max_refunds_exceeded | The maximum number of refunds for this order has been exceeded. | No action possible; the refund limit has already been reached. |
425 | order_payment_not_yet_enabled_for_refund | The order is not yet enabled for refund. | Wait a moment and retry the request. |
428 | insufficient_money_for_refund | Insufficient balance in the account to process the refund. | Check the available balance in the Mercado Pago account before trying again. |
500 | idempotency_validation_failed | Idempotency validation failed. | Retry the request with the same X-Idempotency-Key. |
500 | generic | Internal server error. | Retry the request. If the problem persists, contact support. |