Erro 429: limite de requisições, cota ou tentativas?

O 429 costuma ser tratado como uma coisa só — "passei do limite, espero e tento de novo" —, e essa leitura acerta um caso em três. Na API de assinatura, três situações distintas produzem esse código: o limite de requisições por tempo, o limite de tentativas de uma etapa de verificação, e o esgotamento da cota do plano. Esperar e repetir resolve a primeira, não resolve a segunda e é inútil na terceira. Este guia mostra como distinguir as três pela resposta e o que fazer em cada uma.

Como distinguir, em uma olhada

Daí uma recomendação de instrumentação: registre a resposta inteira, não só o código. Um log com "429" e nada mais torna impossível saber, depois, qual dos três aconteceu — e os três exigem ações diferentes de times diferentes.

Caso 1: limite de requisições

É o 429 clássico, uma proteção de tráfego. A resposta traz o intervalo a respeitar:

Duas regras práticas. Obedeça ao Retry-After em vez de inventar o intervalo — ele é a informação que o servidor tem e você não. E, quando ele não vier, use recuo exponencial com teto, nunca repetição em intervalo fixo.

Melhor ainda é não chegar lá. As respostas trazem RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; alarmar quando o remaining fica baixo avisa antes do primeiro 429. Um alarme que dispara depois chega junto com o incidente, não antes dele. O desenho completo de backoff está em rate limits, paginação e idempotência.

Caso 2: as tentativas da etapa acabaram

Este é o 429 que o recuo exponencial não resolve, porque não há nada a esperar:

Cada etapa de verificação tem um orçamento de tentativas. Quando ele acaba, a etapa é encerrada — e repetir só produz o mesmo 429.

Os orçamentos são por tipo de etapa, e isso tem um efeito útil: etapas biométricas usam o limite biométrico da conta, a checagem de identidade governamental tem o seu próprio, o aviso de finalidade tem exatamente uma tentativa, e as demais usam um teto genérico. Como os orçamentos são separados, esgotar um caminho não esgota o alternativo — é o que faz o plano B ser viável quando ele é acionado.

A conduta correta aqui não é técnica: é de produto. Alguém ficou sem saída, e precisa de um caminho alternativo previsto ou de encaminhamento para atendimento humano. Decidir isso durante o incidente é a pior hora.

Caso 3: a cota do plano acabou

Cota e limite de requisições são controles independentes, e a confusão entre eles é frequente:

A última linha explica um caso que parece contraditório: é possível estar sem cota biométrica e com cota de documento sobrando. As cotas são por método, e esgotar uma não afeta as outras.

Este é o 429 que nunca deveria surpreender, porque existe aviso antes. O evento de aviso de cota é disparado ao cruzar o percentual de alerta da conta, e é literalmente a última chance de reagir antes das recusas — trate-o como alarme, não como log. E o painel traz uma previsão de uso que projeta o fechamento do mês pelo ritmo atual: é o único lugar onde você descobre que vai estourar antes de estourar. Ver o painel de API.

Note também que não existe endpoint público de consulta de cota: o acompanhamento é pelo painel ou pelo evento.

Repetições consomem cota

Um detalhe que liga os casos 2 e 3, e que costuma explicar consumo inesperado: a primeira tentativa de uma etapa já está paga pela criação da transação. Da segunda em diante, cada repetição é debitada, porque cada uma dispara de novo o provedor de verificação.

Um mecanismo de nova tentativa mal calibrado consome cota em silêncio. Vale medir a razão entre documentos enviados e cota consumida: se ela subir sem explicação, normalmente há repetição escondida.

O que implementar

1. Ramifique o 429 pelas três causas antes de decidir a ação — a mensagem e a presença do Retry-After bastam para separar.
2. Obedeça ao Retry-After, e use recuo exponencial com teto quando ele não vier.
3. Observe o campo de nova tentativa nas respostas de etapa, em vez de esperar o 429.
4. Alarme em RateLimit-Remaining baixo e em qualquer aviso de cota.
5. Nunca repita cota esgotada. Isso não é transitório dentro do período.

Para o conjunto de sinais que uma integração deveria observar, veja o que monitorar numa integração. Para o catálogo de códigos, códigos de erro e tratamento de falhas. E a visão geral da API de assinatura eletrônica descreve os métodos que consomem cada cota.

Perguntas Frequentes