Recursos para IA
Possíveis erros
Veja a lista de possíveis erros retornados pelas APIs utilizadas na integração com Wallet Connect e como corrigi-los.
Erros retornados nas operações de criação da vinculação, geração do token de pagamento, consulta e cancelamento.
| Tipo de Erro | Status | Código | Descrição e soluções possíveis |
| Erro de requisição | 400 | RedirectUriMismatch | O URI de redirecionamento não corresponde ao registrado para esta aplicação. Verifique o valor enviado em return_uri e confirme que ele está registrado nas configurações da sua aplicação. |
| Erro de requisição | 400 | ReturnUriNull | O campo return_uri é obrigatório e não foi informado. Faça a requisição novamente incluindo-o. |
| Erro de requisição | 400 | ReturnUriTooLong | O valor de return_uri excede o comprimento máximo permitido de 2048 caracteres. Reduza o tamanho da URI enviada. |
| Erro de requisição | 400 | ExternalUserNull | O campo external_user é obrigatório e não foi informado. Faça a requisição novamente incluindo o identificador do comprador em seu sistema. |
| Erro de requisição | 400 | ExternalFlowIdTooLong | O valor de external_flow_id excede o comprimento máximo permitido de 64 caracteres. Reduza o tamanho do identificador enviado. |
| Erro de requisição | 400 | AgreementDataDescriptionInvalid | O valor de agreement_data.description é inválido. Verifique o conteúdo enviado e respeite o limite de 256 caracteres. |
| Erro de requisição | 400 | CodeMismatch | O código informado não corresponde ao código de validação desta vinculação. Utilize o code retornado na return_uri ou no webhook de confirmação da vinculação correspondente. |
| Erro de requisição | 400 | InvalidCodeFormat | O formato do código é inválido. Deve ser uma string alfanumérica de 32 caracteres em letras minúsculas. |
| Erro de requisição | 400 | AlreadyCreated | Um token de pagamento para esta vinculação já foi gerado. Utilize o payer_token obtido anteriormente, pois o mesmo code não pode ser reutilizado. |
| Erro de requisição | 400 | WindowExpired | A janela de tempo para gerar um token de pagamento expirou. Será necessário criar uma nova vinculação e obter uma nova aprovação do comprador. |
| Erro de requisição | 400 | AgreementNotConfirmedByUser | A vinculação ainda não foi confirmada pelo comprador. Aguarde a conclusão do fluxo de aprovação antes de solicitar o token de pagamento. |
| Erro de requisição | 400 | UserIdEqualsCollectorId | O comprador e o vendedor não podem ser o mesmo usuário do Mercado Pago. Utilize contas distintas para realizar a vinculação. |
| Erro de requisição | 400 | invalid_path_param | O agreement_id fornecido no path não é válido. Verifique e forneça um id válido para tentar novamente. |
| Erro de requisição | 403 | forbidden | Você não tem permissão para acessar o recurso solicitado. Verifique se o Access Token utilizado tem as permissões e escopos necessários para esta operação. |
| Erro de requisição | 404 | AgreementNotFound | Nenhuma vinculação foi encontrada com o ID informado. Essa mesma resposta é retornada quando a vinculação pertence a outra aplicação, a fim de evitar expor a existência de vinculações de outros clientes. |
| Erro de requisição | 404 | ClientNotOwner | A vinculação existe, mas não foi criada pela aplicação atual. Será retornada a mesma resposta de AgreementNotFound para evitar expor a existência de vinculações de outros clientes. |
| Erro de requisição | 404 | AlreadyCancelled | A vinculação já foi cancelada. Lembre-se de que ela também pode ser cancelada pelo próprio comprador pelo aplicativo do Mercado Pago ou automaticamente quando uma nova vinculação é confirmada para o mesmo comprador. |
| 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 retornados nas operações de criação, captura, consulta, cancelamento e reembolso de orders.
| Tipo de Erro | Status | Código | Descrição e soluções possíveis |
| Erro de requisição | 400 | json_syntax_error | Um JSON inválido foi enviado. Certifique-se de que a requisição possua uma estrutura JSON válida e verifique a mensagem retornada nos detalhes do erro para identificar o problema. |
| Erro de requisição | 400 | required_properties | Algumas propriedades obrigatórias estão ausentes. Verifique a mensagem retornada nos detalhes do erro e assegure-se de incluir todas as propriedades requeridas conforme a documentação da API. |
| Erro de requisição | 400 | unsupported_properties | Uma propriedade não suportada pela API foi enviada. 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 enviado. Adicione as propriedades necessárias para completar a solicitação. |
| Erro de requisição | 400 | property_type | O tipo de alguma propriedade informada é inválido. Certifique-se de que o valor enviado na requisição corresponda ao tipo esperado. |
| Erro de requisição | 400 | property_value | O valor de alguma propriedade informada é inválido. Verifique o valor enviado e ajuste-o para que corresponda aos valores permitidos. |
| Erro de requisição | 400 | maximum_items | O tamanho do array excede o máximo permitido. Reduza a quantidade de itens enviados. Lembre-se de que orders de Wallet Connect aceitam apenas uma transação de pagamento. |
| Erro de requisição | 400 | minimum_items | O tamanho do array está abaixo do mínimo permitido. Adicione mais itens à solicitação para cumprir com os requisitos da API. |
| Erro de requisição | 400 | invalid_properties | Informações incorretas foram fornecidas. Revise as propriedades enviadas e verifique se estão de acordo com as especificações da API. |
| Erro de requisição | 400 | invalid_path_param | O order_id fornecido no path não é válido. Verifique e forneça um id válido para tentar novamente. |
| Erro de requisição | 400 | invalid_order_type | O type da order é inválido ou não suportado. Para pagamentos com Wallet Connect, o único valor possível é online. |
| Erro de requisição | 400 | invalid_total_amount | O valor informado em total_amount não equivale à soma do campo transactions.payments.amount do total de transações. Verifique se os valores estão corretos. |
| Erro de requisição | 400 | empty_required_header | O header X-Idempotency-Key é obrigatório e não foi enviado. Faça a requisição novamente incluindo-o. |
| Erro de requisição | 400 | invalid_idempotency_key_length | O valor enviado no header X-Idempotency-Key deve ter entre 1 e 64 caracteres. |
| Erro de requisição | 400 | refund_amount_exceeds | O valor do reembolso é maior do que o valor disponível na transação. Verifique o valor disponível e ajuste o valor solicitado para não exceder esse limite. |
| Erro de autenticação | 401 | unauthorized | O valor enviado como Access Token está incorreto. Verifique e tente enviar a requisição novamente com o valor correto. |
| Erro de autenticação | 401 | unauthorized_payer_token | O payer_token fornecido não está autorizado para esta transação. Verifique se o token é válido, se pertence ao comprador autenticado e se a vinculação não foi cancelada. Caso tenha sido, é necessário repetir o fluxo de vinculação. |
| Erro de autenticaçã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 | A order foi criada mas alguma transação falhou. Verifique o campo errors da resposta para identificar o motivo, como saldo insuficiente na carteira do comprador (insufficient_amount). |
| Erro de requisição | 404 | order_not_found | Order não encontrada. Verifique se o id enviado está correto. |
| Erro de requisição | 404 | payment_not_found | Pagamento não encontrado. Verifique se o payment_id enviado está correto. |
| Erro de requisição | 404 | transaction_not_found | Transação não encontrada. Verifique se o transaction_id enviado está correto. |
| Erro de Idempotência | 409 | idempotency_key_already_used | O valor enviado como header de idempotência (X-Idempotency-Key) já foi utilizado. Cada chave deve ser única para garantir que a operação seja realizada uma única vez. Utilize um novo valor para a próxima solicitação. |
| Erro de requisição | 409 | operation_not_supported | A operação não é suportada para esta order. Verifique o status e o status_detail da order e tente novamente. |
| Erro de requisição | 409 | cannot_capture_order | A order não pode ser capturada porque não está em um status que permite a captura. Apenas orders no status action_required criadas com capture_mode igual a manual podem ser capturadas. |
| Erro de requisição | 409 | cannot_cancel_order | A order não pode ser cancelada porque não está em um status que permite o cancelamento. Apenas orders no status action_required podem ser canceladas. Para reverter um pagamento já capturado, utilize o reembolso. |
| Erro de requisição | 409 | order_already_canceled | A order já foi cancelada. Não é possível realizar operações em uma order que já se encontra nesse status. |
| Erro de requisição | 409 | cannot_refund_order | A order não pode ser reembolsada. Certifique-se de que ela esteja em um status que permita a realização de um reembolso. |
| Erro de requisição | 409 | order_already_refunded | A order já foi totalmente reembolsada. Não é possível processar um novo reembolso nesse cenário. |
| Erro de requisição | 409 | order_refund_already_in_process | Já existe em processamento uma solicitação de reembolso completo para esta order. Aguarde a conclusão antes de enviar uma nova solicitação. |
| Erro de requisição | 422 | unprocessable_entity | O perfil de pagamento associado ao payer_token está corrompido ou incompleto. Solicite ao comprador que refaça a vinculação da carteira. |
| Erro de Idempotência | 423 | resource_locked | A chave de idempotência (X-Idempotency-Key) está bloqueada por uma requisição em andamento. Aguarde alguns instantes e tente executar a requisição novamente. |
| Erro de Idempotência | 500 | idempotency_validation_failed | Falha na validação de idempotência. 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. |
Para obter mais informações sobre como enviar as solicitações, requisitos e validações necessárias, consulte nossa Referência de APIAPI.