Erros e exceções comuns — Pague Contas
Use esta página para identificar a causa de erros retornados ao criar, agendar ou cancelar um pagamento de conta.
Como tratar falhasSe a API aceitar a criação e o pagamento falhar posteriormente, acompanhe o resultado por Webhook e consulte
bill.failReasons. Não utilize consultas periódicas como mecanismo principal para acompanhar mudanças de status.
Erros de agendamento
| Mensagem | Motivo | Como resolver |
|---|---|---|
A conta não pode ser agendada para menos de 1 dia útil | O scheduleDate informado não atende à data mínima permitida para o agendamento. | Para pagamento imediato, não envie scheduleDate. Para agendar, informe uma data futura válida. |
A data de agendamento não pode ser inferior à hoje | O scheduleDate informado está no passado. | Informe uma data válida. Se o pagamento deve ocorrer no mesmo dia, utilize o fluxo de pagamento imediato. |
A data de agendamento é maior que a data de vencimento | O scheduleDate é posterior ao dueDate do boleto. | Ajuste o scheduleDate para uma data igual ou anterior ao vencimento. |
Contas vencidas não podem ser agendadas. | Foi enviado scheduleDate para um boleto vencido. | Não envie scheduleDate. Boletos vencidos são processados como pagamento imediato quando o emissor permite pagamento após o vencimento. |
Pagamento fora do horário limite | O pagamento não pode ser processado no mesmo dia devido ao horário aplicável ao tipo ou valor do boleto. | Realize a operação dentro da janela permitida ou no próximo dia útil. Consulte Pagamento imediato x Pagamento agendado. |
O pagamento não pode ser agendado, pois a empresa/órgão não está disponível... | A empresa ou órgão responsável pelo documento não está disponível para esse processamento. | Não repita a operação nas mesmas condições. Utilize outro canal de pagamento quando o documento não for suportado pelo Pague Contas. |
Erros nos dados do pagamento
| Mensagem | Motivo | Como resolver |
|---|---|---|
Esta conta já foi paga | A linha digitável já está associada a um pagamento do cliente. Faturas de cartão podem utilizar a mesma linha digitável em situações específicas. | Antes de reenviar, confirme se o pagamento já existe e concilie a operação anterior. |
Os dados de pagamento são inválidos. | Os dados enviados não são compatíveis com as informações identificadas no boleto. | Envie somente os campos necessários e revise os valores informados. Quando necessário, utilize a simulação do pagamento antes de criar a operação. |
Não é possível aplicar desconto em contas de consumo e impostos. | O campo discount foi informado para uma conta de consumo ou imposto. | Remova discount da requisição. |
A conta precisa ter valor maior que zero | O campo value, quando necessário, foi enviado com valor igual ou inferior a zero. | Informe um valor maior que zero. |
A descrição não deve ultrapassar X caracteres | O conteúdo de description ultrapassa o limite aceito. | Reduza o conteúdo enviado em description. |
Erros de habilitação e autorização
| Mensagem | Motivo | Como resolver |
|---|---|---|
Você não possui pagamento de contas habilitados, entre em contato com seu gerente. | O Pague Contas não está habilitado para a conta. | Solicite a habilitação ao seu gerente ou contato comercial. |
É obrigatório informar os dados para autorização da ação crítica | A operação exige uma validação adicional de segurança para a conta. | Conclua o fluxo de ação crítica solicitado antes de tentar processar o pagamento novamente. Em Sandbox, consulte Como testar ações críticas. |
Erros de cancelamento
Antes de cancelar um pagamento, verifique o campo canBeCancelled.
| Mensagem ou retorno | Motivo | Como resolver |
|---|---|---|
O pagamento desta conta já está cancelado [id]. | O pagamento já foi cancelado anteriormente. | Não envie uma nova solicitação de cancelamento. Atualize o estado da operação no seu sistema. |
400 Bad Request ao cancelar | O pagamento não atende mais às condições necessárias para cancelamento. | Consulte o pagamento e confirme se canBeCancelled está como true antes de tentar novamente. |
Consulte o endpoint Cancelar pagamento de contas.
Falhas após a criação
Nem toda falha ocorre durante a requisição de criação. Um pagamento pode ser criado e falhar posteriormente durante o processamento.
Ao receber BILL_FAILED:
- localize a operação por
bill.id; - consulte
bill.failReasons; - registre o motivo da falha;
- corrija a causa antes de avaliar uma nova tentativa.
Se bill.failReasons indicar saldo insuficiente, regularize o saldo antes de tentar realizar o pagamento novamente.
Prefira os Webhooks de Pague Contas para atualizar o estado da operação. Utilize consultas à API apenas para reconciliação ou recuperação de estado quando necessário.
Consulte os eventos de Webhook do Pague Contas.
Próximos passos
Updated 13 days ago