Erros e exceções comuns

Mensagem (UI / API)	Motivo técnico (onde ocorre)	Como resolver (ação prática)
`A conta não pode ser agendada para menos de 1 dia útil`	Agendamento para hoje quando não é boleto do Asaas (mínimo = hoje se Asaas; senão, próximo dia útil/limite horário).	Agende para o próximo dia útil ou antes do horário-limite do mesmo dia (se aplicável).
`A data de agendamento não pode ser inferior à hoje`	`scheduleDate` < data atual (validação de mínimo na criação).	Use hoje (para boletos Asaas dentro do horário) ou +1 dia útil.
`A data de agendamento é maior que a data de vencimento`	`scheduleDate` > `dueDate` (para boletos não vencidos).	Ajuste `scheduleDate` ≤ `dueDate` (considera tolerância de feriado).
`Contas vencidas não podem ser agendadas.`	Boleto vencido com `scheduleDate` informado (ou fora da janela “hoje” vs. ontem/amanhã).	Para vencidos: não envie `scheduleDate`; pague no mesmo dia dentro do limite/hora.
(Texto de limite de horário para vencidos) `Pagamento fora do horário limite`	Boleto vencido ou de utilidade/imposto acima do limite do dia (regras de hora-limite).	Reenvie no dia seguinte útil ou antes do horário limite no mesmo dia.
`Pagamentos de contas indisponível em dd/MM/yyyy.`	`scheduleDate` cai em dia não operacional.	Agende para dia útil/operacional.
`O pagamento não pode ser agendado, pois a empresa/órgão não está disponível...`	Empresa/órgão em lista de não suportados para utilidade/imposto.	Não suportado: oriente canal alternativo (internet banking do emissor etc.).
`Esta conta já foi paga`	`linhaDigitavel` já existe para o cliente (exceto faturas de cartão com mesma linha).	Não reenviar mesma linha; confirme pagamento anterior.
`Os dados de pagamento são inválidos.`	Divergência entre linha/vencimento/valor/banco vs. parâmetros enviados (`allowChangeValue`, `dueDate`, `bankId`).	Recalcular parâmetros a partir da linha digitável e reenviar sem divergências.
`Não é possível aplicar desconto em contas de consumo e impostos.`	`discount` informado em utilidade/impostos.	Remova `discount`.
`A conta precisa ter valor maior que zero`	`value` ≤ 0.	Envie valor > 0 (somando juros/multa – desconto).
`A descrição não deve ultrapassar X caracteres`	`description` excede `maxSize`.	Reduza o texto; guarde detalhe no seu `externalReference`.
`Você não possui pagamento de contas habilitados, entre em contato com seu gerente.`	Cliente sem feature de pague contas habilitada.	Solicitar habilitação ao gerente/comercial.
`A data de agendamento é maior que a data de vencimento` (não vencido)	`scheduleDate` > `dueDate` após tolerância de feriado.	Ajustar `scheduleDate` ≤ `dueDate`.
`É obrigatório informar os dados para autorização da ação crítica`	Conta exige Ação Crítica; request sem token/dados (`authorizationData`).	Enviar `authorizationData` (groupId + token) ou aprovar via fluxo de ação crítica.
`FAILED` após `PENDING`	Falha do emissor/rastreamento (ex.: bloqueio, valor inválido, vencido, comunicação, etc.).	Consulte `failReasons` no webhook e tente novamente corrigindo a causa (valor/linha/horário).
Status alterado para `WAITING_MANUAL_PAYMENT`	Regras específicas (ex.: cedente não encontrado, erro de comunicação, valor acima do limite do integrador).	Executar pagamento manual conforme instruções internas ou reprocessar quando liberado.
Falha por saldo insuficiente (mensagem com valores)	Na virada de `SCHEDULED` → `PENDING`, cliente sem saldo para valor+taxa.	Creditar saldo suficiente e reagendar (se necessário).
`Este pagamento de conta não pode ser estornado.`	Título não atende critérios de refund.	Verificar janela e status; quando elegível, use o estorno.
`Esta conta já foi estornada.`	Tentativa de estornar/cancelar algo já estornado/cancelado.	Nenhuma ação; consultar histórico.
`O pagamento desta conta já está cancelado [id].`	`cancel` em item já cancelado.	Nenhuma ação; confirmar status.
`O e-mail informado é inválido.`	`thirdPartyEmail` inválido quando `notifyThirdPartyOnConfirmation = true`.	Corrigir e-mail.
`O celular informado é inválido.`	`thirdPartyPhone` inválido quando `notifyThirdPartyOnConfirmation = true`.	Corrigir número (celular válido).

Notas rápidas por contexto

1) Linha Digitável & Dados

Normalize a linha (só números).
Recalcule dueDate, bankId, originalValue a partir da linha; não force campos divergentes (gera “Os dados de pagamento são inválidos.”).

2) Agendamento

Boleto Asaas: pode hoje (respeitando horário), minimumDaysToSchedule = 0.
Demais boletos: hoje só se dentro do horário-limite; senão, +1 dia útil.
Vencidos: não agendar → pagar no mesmo dia (dentro do limite) e não enviar scheduleDate.
scheduleDate não pode ser > dueDate (para não vencidos).
Dias não operacionais são bloqueados.

3) Valor/Taxas

value > 0 sempre.
Utilidade/Impostos: sem desconto.
Para boleto Asaas, divergência de valor acima da tolerância retorna erro (adequar juros/multa/desconto vs. valor registrado no pagamento).

Dicas de implementação (para evitar armadilhas)

Para vencidos, não mande scheduleDate.
Em utilidade/impostos, nunca envie discount.
Respeite horário-limite e dias não operacionais.
Se usar boleto do próprio Asaas, não force confirmação paralela (erro “já em processamento”).
Trate saldo insuficiente antes da virada do status (cheque saldo ≥ value + fee).