Recursos para IA
Principais status e possíveis erros
Veja abaixo os principais status de uma transação e os possíveis erros de requisição.
Após a criação exitosa do payout, são geradas as transações, que correspondem às transações enviadas no body da solicitação. Quando se cria uma transação, ou quando consulta informações relativas a ela, as respostas retornarão os campos que permitirão conhecer o status em que ela se encontra.
status: este campo fornecerá informações sobre o estado atual do processamento.status_detail: este campo pertence a cada transação e informa os motivos ou detalhes que resultaram nesse status. É retornado comotransactions[].status_detailem uma lista de transações e comostatus_detailna resposta de uma transação individual.
Veja abaixo todos os status pelos quais uma transação pode passar durante seu processamento.
status | status_detail | Descrição |
approved | - | Uma transação foi criada, mas ainda não foi processada. É um status intermediário. |
approved | partially_refunded | A transação foi parcialmente reembolsada pelo banco de destino. |
canceled | - | Uma transação agendada foi cancelada pelo endpoint Cancelar uma transaçãoPUT. |
created | - | A transação foi criada. |
error | failed | Quando ocorre um erro no processo da transação e não se consegue creditar o valor na conta de destino. Veja aqui mais informações sobre as mensagens retornadas. |
error | invalid_chave_pix | A chave Pix enviada é inválida, pertence a uma conta diferente da esperada, ou está na lista de bloqueio. |
error | missing_pix_alias | A chave Pix foi resolvida, mas as informações da conta retornadas estão incompletas para que a transferência prossiga. |
error | downstream_service_unavailable | Ocorreu uma falha transitória ao resolver a chave Pix com o serviço de consulta de destinatário. Indica instabilidade, não uma rejeição de negócio. |
error | incomplete_recipient_data | A chave Pix foi resolvida com sucesso, mas os dados da conta bancária do destinatário estão incompletos. |
error | account_finder_internal_error | Ocorreu um erro interno inesperado ao resolver a chave Pix. |
error | processing_cancelled | Não foi possível concluir a resolução da chave Pix antes que a requisição fosse cancelada. |
processed | approved | O processamento da transação foi bem-sucedido. |
refunded | refunded | A transação foi totalmente reembolsada pelo banco de destino. |
rejected | by_bank | A transação foi rejeitada pelo banco de destino. Execute novamente a solicitação. |
rejected | by_provider | A transação foi rejeitada pelo provedor. Execute novamente a solicitação. |
rejected | high_risk | A transação é rejeitada devido ao risco de fraude. Execute novamente a solicitação. |
rejected | insufficient_funds | A transação foi rejeitada devido a fundos insuficientes na conta de origem. Execute novamente a solicitação. |
rejected | other_reason | A transação foi rejeitada por padrão devido a problemas internos durante o processamento. Execute novamente a solicitação. |
rejected | review_manual | A transação é rejeitada e enviada para análise de prevenção de fraudes. Execute novamente a solicitação. |
success | accredited | A transação encontra-se creditada na conta de destino. |
success | in_progress | A creditação da transação está em processo, ainda não está na conta de destino. |
transaction_in_process | pending_authorized | A transação está em andamento, com status final pendente e aguardando autorização. |
transaction_in_process | pending_bank | O banco de destino não respondeu, portanto, a transação está pendente de um estado final. |
Mensagens de erro da transação
Quando uma transação apresenta status=error e status_detail=failed, a resposta contém uma mensagem amigável que descreve a causa do erro. Para transações Pix, status_detail pode retornar os valores específicos apresentados ao final da tabela.
status_detail | Mensagem |
failed | A conta do pagador não possui fundos suficientes para completar esta transação. Verifique o saldo da conta e tente novamente. |
failed | Não foi possível processar a transação. Ocorreu um erro ao reservar os fundos. Por favor, tente novamente mais tarde ou entre em contato com o suporte. |
failed | Conta TED não encontrada ou inativa. Verifique as informações da conta e tente novamente. |
failed | Não foi possível processar a transação. Ocorreu um erro ao processar os dados da transferência. Por favor, tente novamente mais tarde ou entre em contato com o suporte. |
failed | A transação foi rejeitada. Verifique os detalhes da transação e tente novamente. Se o problema persistir, entre em contato com o suporte. |
failed | Não foi possível processar a transação. Ocorreu um erro interno. Por favor, tente novamente mais tarde ou entre em contato com o suporte. |
failed | Recurso não encontrado. Verifique os detalhes da transação e tente novamente. |
failed | Formato de data inválido. Verifique os campos de data na sua requisição. |
failed | Não foi possível obter informações bancárias. Verifique os dados da conta bancária e tente novamente. |
failed | Informações de usuário inválidas. Verifique os IDs de usuário em sua requisição. |
failed | Estamos temporariamente impossibilitados de exibir o status desta transferência. Isso não significa que a transferência falhou. Por favor, atualize a página em alguns instantes ou entre em contato com o suporte. |
failed | Serviço temporariamente indisponível. Por favor, tente novamente mais tarde. |
failed | Ocorreu um erro inesperado. Por favor, entre em contato com o suporte para obter assistência. |
invalid_chave_pix | A chave Pix é inválida ou pertence a uma conta diferente. Verifique a chave Pix e tente novamente. |
missing_pix_alias | Não foi possível obter todas as informações da conta para esta chave Pix. Verifique a chave Pix e tente novamente. |
account_finder_internal_error | Ocorreu um erro inesperado ao validar a chave Pix. Tente novamente mais tarde ou entre em contato com o suporte. |
downstream_service_unavailable | Não foi possível obter as informações da conta para esta chave Pix. Tente novamente mais tarde. |
processing_cancelled | Não foi possível concluir a validação desta chave Pix a tempo. Tente novamente. |
Aqui você pode encontrar os possíveis erros que podem ocorrer ao realizar uma solicitação de payout, juntamente com suas descrições e possíveis soluções.
Também podem ocorrer os seguintes erros relacionados aos dados ou ao tipo da conta de destino:
| Tipo de Erro | Status | Código | Descrição e soluções possíveis |
| Erro de requisição | 400 | invalid_payout_id | O valor enviado no parâmetro de path payout_id é inválido ou não identifica um payout existente. Verifique o identificador e tente novamente. |
| Erro de requisição | 400 | invalid_transaction_id | O valor enviado no parâmetro de path transaction_id é inválido ou não identifica uma transação existente. Verifique o identificador e tente novamente. |
| Erro de requisição | 400 | invalid_signature | A assinatura enviada no header X-signature é inválida ou não corresponde ao body criptografado da requisição. Verifique se a secret utilizada para gerar a assinatura está correta e se o body enviado é o mesmo utilizado para gerá-la. Para mais informações, acesse Criptografia de segurança. |
| Erro de requisição | 400 | idempotency_key_required | O header obrigatório X-Idempotency-Key não foi enviado. Inclua-o com um valor único e tente realizar a requisição novamente. |
| Erro de requisição | 400 | invalid_account | O objeto account foi enviado sem nenhum campo de identificação. Envie ao menos um email (conta Mercado Pago) ou um number/bank_id (conta bancária). |
| Erro de requisição | 400 | invalid_account_type | O campo account_type foi enviado com um valor fora do conjunto aceito. Os valores aceitos são checking_account ou savings. |
| Erro de requisição | 400 | invalid_account_type_for_site | O valor savings foi enviado para account_type fora do Brasil. |
| Erro de requisição | 401 | invalid_token | O valor enviado como Access Token está incorreto. Verifique e tente enviar a requisição novamente com o valor correto. |
| Erro de requisição | 403 | forbidden | Sem permissão para acessar o recurso. Verifique se o Access Token enviado possui as permissões necessárias. |
| Erro de requisição | 404 | not_found | O recurso solicitado não foi encontrado ou o valor enviado para identificá-lo é inexistente. Valide as informações enviadas nos parâmetros e tente realizar a requisição novamente. |
| Erro de requisição | 412 | precondition_failed | O status da transação não permite o seu cancelamento. Apenas transações com status=pending ou in_process podem ser canceladas. |
| Erro da API | 500 | internal_server_error | Ocorreu um erro inesperado no servidor. Tente enviar a requisição novamente. Se o problema persistir, acione o suporte. |
| Erro da API | 502 | bad_gateway | Ocorreu um erro na integração com um serviço externo. Tente enviar a requisição novamente. Se o problema persistir, acione o suporte. |