Recursos para IA

Posibles errores

Durante la integración con Checkout Pro mediante la API de Orders, pueden ocurrir errores en las solicitudes a los diferentes endpoints. A continuación, se detallan los códigos de error organizados por endpoint, junto con su causa y solución.

Errores al crear una order

Código HTTP	Código de error	Mensaje	Causa y solución
`400`	`empty_required_header`	`Missing HTTP header: X-Idempotency-Key`	Incluye el encabezado `X-Idempotency-Key` con un UUID único en la solicitud.
`400`	`invalid_idempotency_key_length`	`X-Idempotency-Key length exceeds 128 characters`	Reduce la longitud de la clave de idempotencia a un máximo de 128 caracteres.
`400`	`required_properties`	`required property 'email' is missing`	Verifica que todos los campos obligatorios estén presentes en el cuerpo de la solicitud.
`400`	`invalid_total_amount`	`total_amount is not equivalent to sum...`	Verifica que el valor de `total_amount` sea igual a la suma del `unit_price` multiplicado por la `quantity` de todos los ítems de la order.
`400`	`maximum_items`	`maximum 1 items required, but found 2`	Envía solo 1 transacción por order en la solicitud.
`400`	`unsupported_properties`	`An unsupported property was sent. Check the message returned in the error details.`	Se envió un campo no soportado en el cuerpo de la solicitud. Revisa el campo `details` en la respuesta de error para identificar qué propiedad generó el problema, elimínala y vuelve a intentarlo.
`400`	`minimum_properties`	`The minimum number of properties required was not sent. Check the error details`	No se enviaron los campos mínimos requeridos. Revisa el campo `details` en la respuesta de error para identificar qué objeto o sub-objeto tiene campos obligatorios faltantes y reintenta con el payload completo.
`400`	`idempotency_validation_failed`	`Validation fail. Please try submitting the request again`	Error transitorio del servidor al validar la clave de idempotencia. Genera un nuevo `X-Idempotency-Key` y reenvía la solicitud.
`400`	`property_value`	`invalid value 'X', expected one of: online, point, qr`	Utiliza el valor `online` en el campo `type` para integraciones de Checkout Pro.
`400`	`property_type`	`expected string, but got number`	Verifica los tipos de datos de cada campo. Consulta la referencia de la API para más detalles.
`400`	`json_syntax_error`	`An incorrect JSON was sent`	Valida la sintaxis del JSON enviado en el cuerpo de la solicitud.
`400`	`invalid_email_for_sandbox`	`Email must contain '@testuser.com'`	Utiliza correos electrónicos con dominio `@testuser.com` en el entorno de pruebas (sandbox).
`409`	`idempotency_key_already_used`	`X-Idempotency-Key already used...`	Genera una nueva clave de idempotencia. La clave enviada ya fue utilizada en una solicitud anterior.
`423`	`resource_locked`	`Idempotency Key Locked...`	El recurso está siendo procesado con la misma clave de idempotencia. Espera unos segundos e intenta nuevamente.
`500`	`internal_error`	`Some error occurred on our side`	Error interno del servidor. Reintenta la solicitud más tarde.

Errores al consultar una order

Código HTTP	Código de error	Mensaje	Causa y solución
`400`	`invalid_path_param`	`Path param order id is invalid`	Verifica que el ID de la order tenga el formato correcto (ULID).
`404`	`order_not_found`	`order not found`	Verifica que el Access Token corresponda al creador de la order.

Errores al cancelar una order

Código HTTP	Código de error	Mensaje	Causa y solución
`400`	`invalid_path_param`	`Path param order id is invalid`	Verifica que el ID de la order tenga el formato correcto (ULID).
`400`	`empty_required_header`	`Missing HTTP header: X-Idempotency-Key`	Incluye el encabezado `X-Idempotency-Key` con un UUID único.
`404`	`order_not_found`	`order not found`	Verifica que el Access Token corresponda al creador de la order.
`409`	`cannot_cancel_order`	`Only orders with status 'action_required' or 'created'...`	La order se encuentra en un estado incompatible para cancelación. Solo las orders con estado `created` o `action_required` pueden ser canceladas.
`409`	`order_already_cancelled`	`The order has already been canceled`	La order ya fue cancelada anteriormente. No es necesario enviar la solicitud nuevamente.

Errores al reembolsar una order

Código HTTP	Código de error	Mensaje	Causa y solución
`400`	`refund_amount_exceeds`	`Refund amount exceeds the available amount`	El monto del reembolso supera el monto disponible. Verifica el monto disponible para reembolso.
`400`	`order_refund_already_in_process`	`There is already a full refund request in process`	Ya existe una solicitud de reembolso total en proceso. Espera a que se complete antes de enviar una nueva solicitud.
`404`	`transaction_not_found`	`Transaction not found`	Verifica que el ID de la transacción sea correcto.
`409`	`cannot_refund_order`	`Cannot refund order...`	La order debe estar en estado `processed` para poder solicitar un reembolso.

Para más información sobre cómo enviar las solicitudes, los requisitos y las validaciones necesarias, consulta nuestra Referencia de APIAPI.

AnteriorEstado de la orderConsulta los principales estados que una orden puede tener al consultar su información.

PróximoIntroducciónConoce el Mercado Pago MCP Server