Diagnóstico de falhas, pagamentos recusados, timeouts, tentativas de reenvio, prevenção de duplicidade e investigação de erros.
Quando uma chamada falhar, registre o método, a rota, o HTTP, o parameter e o correlation_uuid. Remova dados pessoais e segredos dos logs antes de compartilhá-los. Erros de validação podem usar um corpo diferente do envelope comum; trate cada formato conforme a operação.
1. Erro de autenticação
A API autentica a empresa pelo header api_key. Em respostas 401, confira se o header foi enviado, se a chave pertence à empresa e ao ambiente da URL e se ela não foi redefinida. A redefinição invalida a chave anterior imediatamente; atualize os sistemas que ainda a utilizam.
Os identificadores confirmados para autenticação por chave são auth.api_key_not_found (header ausente) e auth.invalid_api_key (chave inválida). company.inactive também retorna 401 quando a empresa associada não está ativa. Corrija a configuração da credencial ou peça ao administrador da conta para verificar o status da empresa. Não tente corrigir esse caso alterando o corpo de pagamento.
O erro pode trazer message, parameter e correlation_uuid; alguns ambientes omitem error. Não registre nem envie a chave em tickets. Substitua-a por <api-key>.
Veja Chaves e Autenticação da API.
2. Acesso negado por IP
Um 403 com company.ip_access_denied indica que a chamada foi bloqueada pela restrição de IP da empresa. Confira o IP público de saída do servidor e as regras cadastradas no BackOffice. Se houver whitelist, o endereço precisa corresponder a um item; um IP na blocklist continua bloqueado mesmo que também apareça na whitelist. Uma falha ao consultar as regras pode produzir o mesmo identificador. Como a resposta não informa qual regra falhou, encaminhe a correlação ao suporte se o IP e a configuração parecerem corretos.
3. Entender resultado e estados de pagamento
Na API, charge representa a Venda, que pode conter várias operações no array transactions. Consulte GET /charges/{charge_uuid} para ver o estado consolidado e as Transações associadas. Cada elemento de transactions[] corresponde a uma tentativa ou operação.
Use charge.status para a situação da Venda, transactions[].status para o resultado resumido de cada Transação e transactions[].detailed_status para a etapa detalhada do processamento. Por exemplo, uma Venda pode estar DUE enquanto a transação de cartão está REFUSED; o exemplo de POST /charges também mostra uma Venda PAID_PARTIALLY com uma transação individual PAID. Portanto, uma transação paga não garante, isoladamente, que o total da Venda foi quitado.
Antes de tentar novamente, identifique em que etapa ocorreu a falha:
| Situação | Como identificar | O que fazer |
|---|---|---|
| Falha na requisição | HTTP de erro e diagnóstico de autenticação ou validação. | Corrija a causa indicada antes de reenviar. |
| Falha no processamento | Erro interno, de comunicação ou de processamento da operação. | Consulte o recurso; uma falha de comunicação não confirma que a operação ficou sem efeito. |
| Pagamento recusado | A Transação retorna status: REFUSED, mesmo quando a chamada HTTP é concluída. | Confira o resultado da autorização e oriente o comprador conforme o motivo disponível. |
| Pagamento pendente | WAITING_PAYMENT nos fluxos aplicáveis de Pix/Boleto ou uma etapa de processamento ainda não concluída. | Acompanhe o estado e os webhooks antes de informar confirmação de pagamento. |
Em pagamentos com cartão, transactions[].auth_response_code e transactions[].auth_response_message ajudam a investigar uma recusa. Podem vir nulos ou vazios. Interprete-os junto com detailed_status e o meio de pagamento, pois um código isolado não define uma regra universal do emissor ou adquirente. Autorização e captura são etapas diferentes.
A grafia também varia por campo: status usa CANCELED, enquanto detailed_status pode usar CANCELLED. Preserve o valor exatamente como retornado.
Veja Venda e Transação, Status da Venda e Status da Transação.
4. Conflito ou estado incompatível da Transação
Leia o identificador em parameter e consulte a Transação por UUID antes de executar novamente uma ação:
transaction.already_captured(409): a Transação já foi capturada. Confiradetailed_status; não envie uma nova captura para contornar o conflito.transaction.already_canceled(409): a Transação já foi cancelada. Consulte seu estado e não repita o cancelamento como se fosse uma nova operação.transaction.already_expired(409): o prazo da Transação Pixpix-cobexpirou. Confirme a situação atual; a cobrança expirada não volta a ficar válida por repetir o cancelamento.transaction.invalid_status(400): o estado atual não atende à operação. Consulte a Transação e compare com as pré-condições do endpoint, como captura ou cancelamento.
O mesmo vale para a Venda. charge.invalid_status (400) indica que o estado atual não permite a ação solicitada. Por exemplo, o código pode ocorrer ao tentar cancelar uma Venda que não está DUE; essa condição não se aplica automaticamente a outros endpoints.
Consulte Consultar uma venda e Consultar uma transação.
5. Checkout inativo, expirado ou SmartForm
Se o Checkout ou link não abrir, confira se o link ou hash é válido e se o template e a sessão estão ativos. Os erros identificados incluem checkout.not_found (404), checkout.no_active (400), checkout.expired (400) e checkout.is_expired (400). Os dois códigos de expiração aparecem em etapas diferentes; para resolver, use um Checkout ativo e dentro do prazo. Links de pagamento expiram por padrão após três dias; a Venda pode definir outro prazo por expiry_date.
No SmartForm, verifique se a Venda contém smart_form e se public_key e token foram enviados ao formulário conforme Exibir o formulário. Ao atingir o limite de tentativas da sessão, o fluxo retorna HTTP 429 com Param: checkout.smartform_limit_exceeded. O corpo usa Message e Param, com iniciais maiúsculas, em vez do envelope comum. Pare as tentativas e consulte o resultado do pagamento antes de iniciar outra sessão. O prazo de liberação e o procedimento de recuperação permanecem A confirmar.
checkout.template_inactive e checkout.template_no_active indicam que o template está inativo para o fluxo. Verifique a configuração no BackOffice ou peça ao administrador que o ative. Uma sessão expirada não pode ser reutilizada como uma nova tentativa de pagamento.
Veja Checkout e Link de Pagamento, Obter checkout e SmartForm.
6. Erros ao criar ou adicionar Split
Confira seller_uuid, tipo e amount de cada divisão, além das condições da Venda definidas pelo endpoint. Os tipos publicados são AMOUNT, PERCENTAGE e REMAINING. Se a Venda já tiver Split, uma nova tentativa pode retornar charge.split_already_created (409). Outros erros incluem Vendedor duplicado (charge.split_seller_cannot_duplicate), percentual acima do limite (charge.split_exceeded_maximum_percentage), participação abaixo do mínimo (charge.split_exceeded_minimum_amount) ou empresa sem permissão para Split (company.split_not_allowed). Esses erros retornam HTTP 400, exceto o erro de permissão, que retorna 401 no fluxo observado.
Se a soma exceder o valor permitido, a API pode retornar charge.split_greater_than_charge_amout (400); preserve essa grafia no tratamento. Recalcule a distribuição e confira a unidade de amount de cada tipo. Se um Vendedor não existir ou estiver em estado incompatível, consulte o cadastro antes de repetir. Para incluir Split depois da criação, a Venda precisa atender às condições de autorização ou captura de Adicionar split na venda.
Veja Split e Vendedores e Consultar split.
7. Timeout: confirme o estado antes de agir
Um timeout indica que o cliente não recebeu resposta a tempo. Isso não confirma se o provedor concluiu a operação. Antes de reenviar o pagamento, consulte GET /charges/{charge_uuid} e, se necessário, GET /transactions/{transaction_uuid}. Se não tiver o UUID da Transação, GET /transactions aceita filtros como charge_uuid, gateway_id, external_id e status; a resposta é paginada.
Se a criação terminou sem resposta e você não recebeu o UUID, consulte Vendas por order_id. A busca é parcial e paginada; confira a referência completa, o ambiente, os valores e o horário para identificar a Venda correta. O filtro não garante resultado único nem substitui idempotência. GET /transactions não aceita filtro documentado por order_id; quando tiver o UUID da Venda, use charge_uuid nessa consulta.
Se o estado mostrar uma transação concluída, não crie outra cobrança para compensar a falta de resposta. Se o resultado permanecer inconclusivo, encaminhe correlation_uuid, UUID da Venda, horário e ambiente ao suporte.
8. Quando repetir uma chamada
Erros de autenticação, IP, validação, estado incompatível, template inativo ou expirado e limite de tentativas exigem corrigir a causa antes de reenviar. Repetir a chamada sem mudança tende a retornar o mesmo erro. charge.max_attempts_reached (400) indica que a Venda chegou ao limite de tentativas de pagamento. Pare os envios para essa Venda, consulte seu estado e peça orientação sobre o próximo procedimento.
Após uma falha de rede ou timeout, consulte o estado do recurso antes de repetir. Em POST /charges/{charge_uuid}/pay, o header opcional idempotency-key aceita UUID e identifica a solicitação. Na repetição da mesma operação, mantenha a chave e o corpo. A referência documenta 409 quando a chave está associada a outro payload, a solicitação continua em processamento, a tentativa anterior falhou ou o resultado está indisponível. Não use a mesma chave com um payload diferente.
O mecanismo está documentado em Criar venda, Pagar venda em aberto e Simular pagamento Pix/Boleto, esta última somente no Sandbox. Não presuma suporte nas demais rotas. Sem idempotency-key, essas operações não oferecem o controle de deduplicação por chave. Diante de um conflito, consulte o estado antes de agir.
9. Procedimento de diagnóstico
- Anote o código HTTP, o endpoint e se a chamada recebeu uma resposta completa ou falhou na conexão.
- Leia
parameter,errors[]ou o formato específico retornado. Consulte Códigos de erros. - Confira o ambiente, a autenticação e os campos enviados conforme o contrato do endpoint.
- Consulte a Venda e as Transações para verificar se houve efeito financeiro.
- Registre a correlação e decida se é preciso corrigir a chamada, acompanhar o recurso ou acionar o suporte. Consulte as convenções de resposta para interpretar o corpo.
Boas práticas de integração
Valide os dados antes de enviar a chamada e registre HTTP, identificador do erro e correlação. Mantenha as credenciais no servidor e limite o acesso aos logs.
Trate respostas vazias, campos opcionais ou nulos e erros não previstos. Se o corpo não tiver o JSON esperado, guarde uma cópia sanitizada e confira o recurso antes de repetir uma operação financeira. Exiba ao comprador apenas mensagens adequadas; mantenha detalhes técnicos nos registros da equipe.
Após uma falha transitória de comunicação, confira o estado atual antes de agir. Defina a política de tentativas para cada operação e não repita recusas, conflitos ou erros de configuração sem corrigir a causa. Quando o endpoint oferecer idempotência, guarde a chave junto da solicitação.
Dados para encaminhar ao suporte
Informe o ambiente, método e rota, horário com fuso, HTTP, parameter, correlation_uuid e os UUIDs da Venda e da Transação, se disponíveis. Para pagamentos, inclua charge.status, transactions[].status, transactions[].detailed_status e, quando pertinentes, auth_response_code e auth_response_message. Remova api_key, número completo do cartão, CVV, tokens e dados pessoais antes de enviar.