Recursos para IA
Possíveis erros da API
Veja a lista de possíveis erros retornados pela API de Orders e como corrigi-los. Os erros que podem ocorrer em mais de uma operação estão agrupados como erros comuns, enquanto os demais estão organizados conforme o endpoint.
Estes erros podem ocorrer em mais de um endpoint da API de Orders.
| Tipo de Erro | Status | Código | Descrição e soluções possíveis |
| Erro de requisição | 400 | json_syntax_error | Certifique-se de que a requisição possua uma estrutura JSON válida, com chaves e valores adequados. |
| Erro de requisição | 400 | required_properties | Algumas propriedades obrigatórias estão ausentes. Verifique a solicitação e assegure-se de incluir todas as propriedades requeridas conforme a documentação da API. |
| Erro de requisição | 400 | unsupported_properties | Algumas propriedades informadas não são suportadas pela API. Revise a solicitação e remova ou corrija as propriedades não suportadas. |
| Erro de requisição | 400 | minimum_properties | O número mínimo de propriedades requeridas não foi atendido. Adicione as propriedades necessárias para completar a solicitação. |
| Erro de requisição | 400 | property_type | O tipo da propriedade informada é invalido. Certifique-se de que o valor enviado na requisição corresponda ao tipo esperado. |
| Erro de requisição | 400 | property_value | O valor da propriedade informado é invalido. Verifique o valor enviado e ajuste-o para que corresponda aos valores permitidos. |
| Erro de requisição | 400 | maximum_items | O número máximo de itens permitidos foi excedido. Reduza a quantidade de itens enviados para que não ultrapasse o máximo permitido. |
| Erro de requisição | 400 | minimum_items | O número mínimo de itens requerido não foi atendido. Adicione mais itens à solicitação para cumprir com os requisitos da API. |
| Erro de requisição | 400 | invalid_path_param | Verifique se o ID fornecido como parâmetro é válido. |
| Erro de requisição | 400 | invalid_properties | Algumas propriedades informadas são inválidas ou estão com formato incorreto. Revise as propriedades enviadas e verifique se estão de acordo com as especificações da API. |
| Erro de requisição | 400 | empty_required_header | Um ou mais headers obrigatórios estão vazios. Verifique a solicitação e assegure-se de que todos os headers obrigatórios estão presentes e devidamente preenchidos. |
| Erro de requisição | 400 | invalid_idempotency_key_length | O valor enviado no header X-Idempotency-Key excedeu o tamanho máximo permitido. O header aceita valores entre 1 e 128 caracteres. |
| Erro de requisição | 400 | invalid_order_mode_for_operation | O modo informado não é válido para esta operação. Verifique se está utilizando o modo correto conforme a operação desejada. |
| Erro de requisição | 400 | invalid_transaction_id | O ID da transação é inválido. Certifique-se de que o ID está correto. |
| Erro de requisição | 400 | invalid_total_amount | O valor informado em total_amount não corresponde à soma dos valores de transactions.payments.amount de todas as transações. Verifique se os valores estão corretos e se a soma dos valores das transações corresponde ao total_amount informado. |
| Erro de requisição | 401 | 401 | O Access Token enviado está incorreto. Revise o valor e tente enviar a requisição novamente com a informação correta. |
| Erro de requisição | 401 | invalid_credentials | Não há suporte para credenciaisChaves de acesso únicas que usamos para identificar uma integração na sua conta, estando vinculadas à sua aplicação. Para mais informações, acesse o link abaixo.Credenciais de teste. Utilize usuários de teste com credenciais de produção para o ambiente de teste (sandbox) e as suas credenciais de produção para o ambiente de produção. |
| Erro de processamento | 402 | failed | Ocorreu um erro no processamento de alguma das transações. Verifique a mensagem para mais informações. |
| Erro de requisição | 403 | forbidden | A aplicação não tem permissão para acessar este recurso. Verifique se o Access Token utilizado tem as permissões e escopos necessários para esta operação. |
| Erro de requisição | 403 | PA_UNAUTHORIZED_RESULT_FROM_POLICIES | A conta está bloqueada e suas chaves de API foram revogadas. Ao menos uma política avaliada pelo Policy Agent retornou um resultado não autorizado. Entre em contato com o Suporte do Mercado Pago para desbloquear sua conta. |
| Erro de requisição | 404 | order_not_found | A order não foi encontrada. Verifique se o ID informado está correto. |
| Erro de Idempotência | 409 | idempotency_key_already_used | A chave X-Idempotency-Key fornecida já foi utilizada. Cada chave de idempotência deve ser única para garantir que a operação seja realizada uma única vez. Utilize uma nova chave para a próxima solicitação. |
| Erro de requisição | 429 | usage_quota_exceeded | Limite de requisições por cliente atingido. Leia o header Retry-After da resposta e aguarde o número de segundos indicado antes de tentar novamente. Para maior resiliência, implemente backoff exponencial com jitter, ou seja, aumente o tempo de espera a cada nova tentativa e adicione uma variação aleatória para evitar o reenvio simultâneo de muitas requisições. |
| Erro de Idempotência | 500 | idempotency_validation_failed | Ocorreu um erro interno no servidor. Tente reenviar a requisição com uma chave de idempotência nova e única para evitar conflitos. Se o problema persistir, entre em contato com o suporte, forneça o x-request-id e mais detalhes sobre a operação realizada. |
| Erro da api | 500 | internal_error | Ocorreu um erro interno no servidor. Por favor, tente novamente mais tarde. Se o problema persistir, entre em contato com o suporte, forneça o x-request-id e mais detalhes sobre a operação realizada. |
Erros específicos do endpoint /v1/ordersPOST.
| Tipo de Erro | Status | Código | Descrição e soluções possíveis |
| Erro de requisição | 400 | order_builder_without_transactions | Não há uma transação associada a order. Certifique-se de incluir ao menos uma transação à criação da order. |
| Erro de requisição | 400 | invalid_order_type | Tipo da order é inválido. Verifique se o tipo utilizado é válido para a operação. |
| Erro de requisição | 400 | invalid_email_for_sandbox | O formato de e-mail é inválido para o ambiente de sandbox, deve conter "@testuser.com". |
| Erro de requisição | 400 | property_value | O domínio informado em payer.email não é permitido. Utilize um e-mail com um domínio válido. |
| Erro de requisição | 400 | property_value | O e-mail informado em payer.email contém palavras não permitidas. Revise o valor enviado e utilize um e-mail válido. |
| Erro de requisição | 400 | property_value | O valor de config.location.state_id não é válido para o site da order. Envie um código válido no formato documentado. |
| Erro de requisição | 400 | property_value | O valor de expiration_time no nível da order não é uma duração ISO 8601 válida. Envie uma duração no formato ISO 8601 (por exemplo, PT2H). |
| Erro de requisição | 400 | property_value | O valor de expiration_time no nível da order excede 2920 horas. Envie uma duração de até 2920 horas. |
| Erro de requisição | 400 | order_invalid_sponsor_id | O identificador do patrocinador da order é inválido. Certifique-se de que o ID está correto. |
| Erro de requisição | 400 | invalid_header_value | Identificador do chamador (caller_id) não encontrado. Certifique-se de que o ID está correto. |
| Erro de Idempotência | 423 | resource_locked | A chave de idempotência está temporariamente bloqueada. Aguarde alguns instantes e tente executar a requisição novamente. |
Erros específicos do endpoint /v1/ordersGET.
| Tipo de Erro | Status | Código | Descrição e soluções possíveis |
| Erro de requisição | 400 | required_search_params | Faltam os parâmetros de busca obrigatórios. Inclua begin_date e end_date na requisição. |
| Erro de requisição | 400 | invalid_search_params | Um ou mais parâmetros de busca são inválidos. Verifique os detalhes da resposta e corrija o formato das datas, a paginação, a ordenação ou os filtros. |
Erro específico do endpoint /v1/orders/{order_id}/transactionsPOST.
| Tipo de Erro | Status | Código | Descrição e soluções possíveis |
| Erro de requisição | 400 | exceeded_number_of_transactions | Ocorreu um erro na requisição. A order aceita, no máximo, uma transação. Remova as transações excedentes. |
Erros específicos do endpoint /v1/orders/{order_id}/refundPOST.
| Tipo de Erro | Status | Código | Descrição e soluções possíveis |
| Erro de requisição | 400 | refund_amount_exceeds | O valor solicitado para reembolso é maior que o valor disponível para reembolso na order. Verifique o valor disponível para reembolso e ajuste o valor solicitado para não exceder esse limite. |
| Erro de requisição | 404 | transaction_not_found | A transação não foi encontrada. Verifique se o ID informado está correto. |
| Erro de requisição | 409 | cannot_refund_order | Certifique-se de que a order esteja em um status que permita a realização de um reembolso. |
| Erro de requisição | 409 | order_already_refunded | A order informada já foi reembolsada. Não é possível processar um reembolso em uma Order que já possui esse status. |
| Erro de requisição | 409 | order_refund_already_in_process | Já existe em processamento uma solicitação de reembolso completo para a order em questão. |
Erros específicos do endpoint /v1/orders/{order_id}/capturePOST.
| Tipo de Erro | Status | Código | Descrição e soluções possíveis |
| Erro de requisição | 409 | cannot_capture_order | Verifique se o status da order permite a captura e se a order foi criada com o campo processing_mode definido como automatic. |
| Erro de requisição | 409 | operation_not_supported | A operação solicitada não é suportada. Verifique se a operação que você está tentando realizar é válida para o contexto atual. |
Erros específicos do endpoint /v1/orders/{order_id}/cancelPOST.
| Tipo de Erro | Status | Código | Descrição e soluções possíveis |
| Erro de requisição | 409 | cannot_cancel_order | Certifique-se de que a order esteja em um status que permita cancelamento. |
| Erro de requisição | 409 | order_already_canceled | A order informada já foi cancelada. Não é possível realizar operações em uma order que já se encontra cancelada. |
Para obter mais informações sobre como enviar as solicitações, requisitos e validações necessárias, consulte nossa Referência de APIAPI.