Recursos para IA

Possíveis erros

Durante a integração de Checkout Pro através da API de Orders, as requisições aos endpoints podem retornar erros. A tabela a seguir apresenta os códigos de erro agrupados por endpoint, bem como suas respectivas descrições, causas e ações recomendadas para correção.

Erros ao criar uma order

Código HTTP	Código de erro	Mensagem	Causa e solução
`400`	`empty_required_header`	`Missing HTTP header: X-Idempotency-Key`	Inclua o header `X-Idempotency-Key` com um UUID único na solicitação.
`400`	`invalid_idempotency_key_length`	`X-Idempotency-Key length exceeds 128 characters`	Reduza o comprimento da chave de idempotência para no máximo 128 caracteres.
`400`	`required_properties`	`required property 'email' is missing`	Verifique se todos os campos obrigatórios estão presentes no corpo da solicitação.
`400`	`invalid_total_amount`	`total_amount is not equivalent to sum...`	Verifique se o valor de `total_amount` é igual à soma do `unit_price` multiplicado pela `quantity` de todos os itens da order.
`400`	`maximum_items`	`maximum 1 items required, but found 2`	Envie apenas uma transação por order na solicitação.
`400`	`unsupported_properties`	`An unsupported property was sent. Check the message returned in the error details.`	Um campo não suportado foi incluído no corpo da solicitação. Verifique o campo `details` na resposta de erro para identificar qual propriedade causou o problema, remova-a e tente novamente.
`400`	`minimum_properties`	`The minimum number of properties required was not sent. Check the error details`	A solicitação não incluiu o número mínimo de propriedades obrigatórias. Verifique o campo `details` na resposta de erro para identificar qual objeto ou sub-objeto está com campos obrigatórios faltando e tente novamente com o payload completo.
`400`	`idempotency_validation_failed`	`Validation fail. Please try submitting the request again`	O servidor não conseguiu validar a chave de idempotência. Este é um erro transitório do lado do servidor. Gere um novo `X-Idempotency-Key` e reenvie a solicitação.
`400`	`property_value`	`invalid value 'X', expected one of: online, point, qr`	Utilize o valor `online` no campo `type` para integrações de Checkout Pro.
`400`	`property_type`	`expected string, but got number`	Verifique os tipos de dados de cada campo. Consulte a referência da API para mais detalhes.
`400`	`json_syntax_error`	`An incorrect JSON was sent`	Valide a sintaxe do JSON enviado no corpo da solicitação.
`400`	`invalid_email_for_sandbox`	`Email must contain '@testuser.com'`	Utilize e-mails com domínio `@testuser.com` no ambiente de testes (sandbox).
`409`	`idempotency_key_already_used`	`X-Idempotency-Key already used...`	Gere uma nova chave de idempotência. A chave enviada já foi utilizada em uma solicitação anterior.
`423`	`resource_locked`	`Idempotency Key Locked...`	O recurso está sendo processado com a mesma chave de idempotência. Aguarde alguns segundos e tente novamente.
`500`	`internal_error`	`Some error occurred on our side`	Erro interno do servidor. Tente novamente mais tarde.

Erros ao consultar uma order

Código HTTP	Código de erro	Mensagem	Causa e solução
`400`	`invalid_path_param`	`Path param order id is invalid`	Verifique se o ID da order está no formato correto (ULID).
`404`	`order_not_found`	`order not found`	Verifique se o Access Token corresponde ao criador da order.

Erros ao cancelar uma order

Código HTTP	Código de erro	Mensagem	Causa e solução
`400`	`invalid_path_param`	`Path param order id is invalid`	Verifique se o ID da order está no formato correto (ULID).
`400`	`empty_required_header`	`Missing HTTP header: X-Idempotency-Key`	Inclua o header `X-Idempotency-Key` com um UUID único.
`404`	`order_not_found`	`order not found`	Verifique se o Access Token corresponde ao criador da order.
`409`	`cannot_cancel_order`	`Only orders with status 'action_required' or 'created'...`	A order está em um status incompatível para cancelamento. Apenas orders com status `created` ou `action_required` podem ser canceladas.
`409`	`order_already_cancelled`	`The order has already been canceled`	A order já foi cancelada anteriormente. Não é necessário enviar a solicitação novamente.

Erros ao reembolsar uma order

Código HTTP	Código de erro	Mensagem	Causa e solução
`400`	`refund_amount_exceeds`	`Refund amount exceeds the available amount`	O valor do reembolso excede o valor disponível. Verifique o valor disponível para reembolso.
`400`	`order_refund_already_in_process`	`There is already a full refund request in process`	Já existe uma solicitação de reembolso total em processamento. Aguarde a conclusão antes de enviar uma nova solicitação.
`404`	`transaction_not_found`	`Transaction not found`	Verifique se o ID da transação está correto.
`409`	`cannot_refund_order`	`Cannot refund order...`	A order deve estar com status `processed` para que um reembolso possa ser solicitado.

Para obter mais informações sobre como enviar as solicitações, requisitos e validações necessárias, consulte nossa Referência de APIAPI.

AnteriorStatus da orderConfira os principais status que uma order pode ter ao consultar suas informações.

PróximoIntroduçãoConheça o Mercado Pago MCP Server