Recursos para IA

Posibles errores de la API

Consulta la lista de posibles errores devueltos por la API de Orders y cómo corregirlos. Los errores que pueden ocurrir en más de una operación están agrupados como errores comunes, mientras que los demás están organizados según el endpoint.

Errores comunes

Estos errores pueden ocurrir en más de un endpoint de la API de Orders.

Tipo de Error	Status	Código	Descripción y soluciones posibles
Error de solicitud	400	`json_syntax_error`	Asegúrate de que la solicitud tenga una estructura JSON válida, con claves y valores adecuados.
Error de solicitud	400	`required_properties`	Algunas propiedades obligatorias están ausentes. Verifica la solicitud y asegúrate de incluir todas las propiedades requeridas según la documentación de la API.
Error de solicitud	400	`unsupported_properties`	Algunas propiedades informadas no son soportadas por la API. Revisa la solicitud y elimina o corrige las propiedades no soportadas.
Error de solicitud	400	`minimum_properties`	No se ha cumplido el número mínimo de propiedades requeridas. Agrega las propiedades necesarias para completar la solicitud.
Error de solicitud	400	`property_type`	El tipo de la propiedad informada es inválido. Asegúrate de que el valor enviado en la solicitud corresponda al tipo esperado.
Error de solicitud	400	`property_value`	El valor de la propiedad informada es inválido. Verifica el valor enviado y haz los ajustes para que corresponda a los valores permitidos.
Error de solicitud	400	`maximum_items`	Se ha excedido el número máximo de ítems permitidos. Reduce la cantidad de ítems enviados para que no sobrepase el máximo permitido.
Error de solicitud	400	`minimum_items`	No se ha cumplido el número mínimo de ítems requerido. Agrega más ítems a la solicitud para cumplir con los requisitos de la API.
Error de solicitud	400	`invalid_path_param`	Verifica si el ID proporcionado como parámetro es válido.
Error de solicitud	400	`invalid_properties`	Algunas propiedades informadas son inválidas o están mal formadas. Revisa las propiedades enviadas y verifica si están de acuerdo con las especificaciones de la API.
Error de solicitud	400	`empty_required_header`	Uno o más headers obligatorios están vacíos. Verifica la solicitud y asegúrate de que todos los headers requeridos están presentes y debidamente completados.
Error de solicitud	400	`invalid_idempotency_key_length`	El valor enviado en el header `X-Idempotency-Key` excedió el tamaño máximo permitido. El header acepta valores entre 1 y 128 caracteres.
Error de solicitud	400	`invalid_order_mode_for_operation`	El modo informado no es válido para esta operación. Verifica si estás utilizando el modo correcto según la operación deseada.
Error de solicitud	400	`invalid_transaction_id`	El ID de la transacción es inválido. Asegúrate de que el ID es correcto.
Error de solicitud	400	`invalid_total_amount`	El valor informado en `total_amount` no corresponde a la suma de los valores de `transactions.payments.amount` de todas las transacciones. Verifica que los valores sean correctos y que su suma corresponda al `total_amount` informado.
Error de solicitud	401	`401`	El valor enviado como Access Token es incorrecto. Por favor, verifícalo y vuelve a intentar realizar la requisición enviando el valor correcto.
Error de solicitud	401	`invalid_credentials`	No hay soporte para credencialesClaves de acceso vinculadas a una aplicación que permiten identificar y autenticar una integración con Mercado Pago.Credenciales de prueba. Usa usuarios de prueba con credenciales de producción para el entorno de prueba (sandbox) y tus credenciales de producción para el entorno de producción.
Error de solicitud	402	`failed`	Hubo un error en el procesamiento de alguna de las transacciones. Verifica el mensaje devuelto para más información.
Error de solicitud	403	`forbidden`	La aplicación no tiene permisos para acceder a este recurso. Verifica que el Access Token utilizado tenga los permisos y scopes necesarios para esta operación.
Error de solicitud	403	`PA_UNAUTHORIZED_RESULT_FROM_POLICIES`	La cuenta está bloqueada y sus claves de API fueron revocadas. Al menos una política evaluada por el Policy Agent retornó un resultado no autorizado. Comunícate con Soporte de Mercado Pago para desbloquear tu cuenta.
Error de solicitud	404	`order_not_found`	La order no fue encontrada. Verifica si el ID informado es correcto.
Error de solicitud	409	`idempotency_key_already_used`	La clave `X-Idempotency-Key` proporcionada ya ha sido utilizada. Cada clave de idempotencia debe ser única para garantizar que la operación se realice una única vez. Utiliza una nueva clave para la próxima solicitud.
Error de solicitud	429	`usage_quota_exceeded`	Límite de solicitudes por cliente alcanzado. Lee el header `Retry-After` de la respuesta y espera la cantidad de segundos indicada antes de volver a intentarlo. Para mayor resiliencia, implementa backoff exponencial con jitter, es decir, aumenta el tiempo de espera en cada nuevo intento y añade una variación aleatoria para evitar el reenvío simultáneo de muchas solicitudes.
Error de la API	500	`idempotency_validation_failed`	Ocurrió un error interno en el servidor. Intenta reenviar la solicitud con una clave de idempotencia nueva y única para evitar conflictos. Si el problema persiste, comunícate con Soporte y proporciona el `x-request-id` junto a más detalles sobre la operación realizada.
Error de la API	500	`internal_error`	Ocurrió un error interno en el servidor. Por favor, intenta nuevamente más tarde. Si el problema persiste, comunícate con Soporte y proporciona el `x-request-id` junto a más detalles sobre la operación realizada.

Crear order

Errores específicos del endpoint /v1/ordersPOST.

Tipo de Error	Status	Código	Descripción y soluciones posibles
Error de solicitud	400	`order_builder_without_transactions`	No hay una transacción asociada a la order. Asegúrate de incluir al menos una transacción para la creación de la order.
Error de solicitud	400	`invalid_order_type`	El tipo de la order es inválido. Verifica si el tipo utilizado es válido para la operación.
Error de solicitud	400	`property_value`	El dominio informado en `payer.email` no está permitido. Utiliza un correo electrónico con un dominio válido.
Error de solicitud	400	`property_value`	El correo electrónico informado en `payer.email` contiene palabras no permitidas. Revisa el valor enviado y utiliza un correo electrónico válido.
Error de solicitud	400	`property_value`	El valor de `config.location.state_id` no es válido para el sitio de la order. Envía un código válido en el formato documentado.
Error de solicitud	400	`property_value`	El valor de `expiration_time` en el nivel de la order no es una duración ISO 8601 válida. Envía una duración en formato ISO 8601 (por ejemplo, `PT2H`).
Error de solicitud	400	`property_value`	El valor de `expiration_time` en el nivel de la order supera las 2920 horas. Envía una duración de hasta 2920 horas.
Error de solicitud	400	`order_invalid_sponsor_id`	El identificador del patrocinador de la order es inválido. Asegúrate de que el ID sea correcto.
Error de solicitud	400	`invalid_header_value`	Identificador del llamador (`caller_id`) no encontrado. Asegúrate de que el ID sea correcto.
Error de solicitud	423	`resource_locked`	La clave de idempotencia está temporalmente bloqueada. Espera unos instantes y trata de ejecutar la solicitud nuevamente.

Buscar orders

Errores específicos del endpoint /v1/ordersGET.

Tipo de Error	Status	Código	Descripción y soluciones posibles
Error de solicitud	400	`required_search_params`	Faltan los parámetros de búsqueda obligatorios. Incluye `begin_date` y `end_date` en la solicitud.
Error de solicitud	400	`invalid_search_params`	Uno o más parámetros de búsqueda no son válidos. Revisa los detalles de la respuesta y corrige el formato de las fechas, la paginación, el ordenamiento o los filtros.

Agregar transacción

Error específico del endpoint /v1/orders/{order_id}/transactionsPOST.

Tipo de Error	Status	Código	Descripción y soluciones posibles
Error de solicitud	400	`exceeded_number_of_transactions`	Ocurrió un error en la solicitud. La Order acepta un máximo de una transacción. Elimine las transacciones excedentes.

Reembolsar order

Errores específicos del endpoint /v1/orders/{order_id}/refundPOST.

Tipo de Error	Status	Código	Descripción y soluciones posibles
Error de solicitud	400	`refund_amount_exceeds`	El valor solicitado para reembolso es mayor que el valor disponible para reembolso en la order. Verifica el valor disponible para devoluciones y ajusta el campo para no exceder ese límite.
Error de solicitud	404	`transaction_not_found`	La transacción no fue encontrada. Verifica si el ID informado es correcto.
Error de solicitud	409	`cannot_refund_order`	Asegúrate de que la order esté en un estado que permita la realización de un reembolso.
Error de solicitud	409	`order_already_refunded`	La order informada ya fue reembolsada. No es posible procesar un reembolso en una order que ya tiene este estado.
Error de solicitud	409	`order_refund_already_in_process`	Ya existe una solicitud de reembolso completo en proceso para la order en cuestión.

Capturar order

Errores específicos del endpoint /v1/orders/{order_id}/capturePOST.

Tipo de Error	Status	Código	Descripción y soluciones posibles
Error de solicitud	409	`cannot_capture_order`	Verifica si el estado de la order permite la captura y que esta haya sido creada con el campo `processing_mode` definido como `automatic`.
Error de solicitud	409	`operation_not_supported`	La operación solicitada no es soportada. Verifica si la operación que estás tratando de realizar es válida para el contexto actual.

Cancelar order

Errores específicos del endpoint /v1/orders/{order_id}/cancelPOST.

Tipo de Error	Status	Código	Descripción y soluciones posibles
Error de solicitud	409	`cannot_cancel_order`	Asegúrate de que la order esté en un estado que permita su cancelación.
Error de solicitud	409	`order_already_canceled`	La order informada ya fue cancelada. No es posible realizar operaciones en una order que ya se encuentra cancelada.

Para obtener más información sobre cómo enviar las solicitudes, requerimientos y 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óximoPosibles errores del SDK móvilVe los principales errores que pueden aparecer en la integración móvil del Checkout API usando el Mercado Pago SDK.