Erro 429 — Collections

O erro 429 na API de Cobranças indica uma tentativa de alterar o estado de uma cobrança que já se encontra em um estado final ou que está temporariamente bloqueada para modificações.

Resumo do problema

Uma chamada de PUT ou DELETE que retorna 429 indica que a operação não pode ser executada sobre a cobrança no estado atual. A cobrança chegou ao servidor corretamente, mas a transição de estado solicitada é inválida.

Motivos recorrentes

Cobrança já cancelada

Uma cobrança com status CANCELED está em estado final e não pode ser alterada ou cancelada novamente. Qualquer PUT ou DELETE sobre ela retornará 429.

Consulte o status atual da cobrança via GET /{companyId}/banking/collections/{collectionId} antes de executar operações de escrita.

Cobrança já paga

Uma cobrança com status PAID está em estado final. Tentativas de atualização (PUT) ou cancelamento (DELETE) retornarão 429.

Cobrança paga aguardando liquidação (janelas CIP)

Este é o caso mais sutil: a cobrança está tecnicamente com status PAID, mas ainda não foi liquidada (settledAt ausente). Nesse estado, ela permanece bloqueada para modificações até que a liquidação seja processada.

A liquidação de boletos ocorre em duas janelas diárias definidas pela CIP:

Janela	Horário de corte	Liquidação
Janela 1	Até 13h30	14h do mesmo dia
Janela 2	Após 13h30	2h do dia seguinte

Boletos pagos após as 13h30 caem na janela das 2h e só são liquidados na madrugada seguinte. Durante esse intervalo, tentativas de PUT ou DELETE retornarão 429.

Resolução: aguarde a liquidação da cobrança e tente a operação novamente após a janela correspondente.

Diagnóstico rápido

1. Consulte o status atual da cobrança via GET /{companyId}/banking/collections/{collectionId}
2. Se o status for CANCELED ou PAID com settledAt preenchido, a cobrança está em estado final e não pode ser alterada
3. Se o status for PAID sem settledAt, a cobrança aguarda liquidação — verifique o horário do pagamento e aguarde a janela CIP correspondente (14h ou 2h)
4. Se o status for PROCESSING ou UPDATING, aguarde a conclusão do processamento antes de tentar novamente

Caso o problema persista após esses passos, entre em contato com a equipe de suporte pelo e-mail ImplantacaoEmpresas@btgpactual.com.