HTTP 429 na integração fiscal

O que significa receber um HTTP 429 ao emitir notas fiscais?

Toda resposta de uma API vem acompanhada de um código numérico do protocolo HTTP. O código 429, chamado Too Many Requests (muitas requisições), avisa que o sistema cliente ultrapassou a quantidade de chamadas permitida em determinado intervalo de tempo.

Na integração fiscal, isso costuma acontecer quando um ERP, marketplace ou plataforma de vendas dispara muitas emissões, consultas de status ou downloads de XML ao mesmo tempo. A requisição recusada não foi processada: a nota não foi enviada ao fisco, nem rejeitada por ele. O pedido apenas precisa ser repetido mais tarde.

Por que uma API fiscal limita a quantidade de requisições?

O limite, conhecido como rate limit, protege a estabilidade do serviço. Sem ele, um único cliente com um laço de repetição defeituoso ou um pico de vendas poderia sobrecarregar a infraestrutura e atrasar a emissão de todos os outros usuários.

Além disso, os próprios sistemas do fisco, como as SEFAZ e as prefeituras, têm capacidade limitada e regras contra consumo excessivo. Controlar o volume na camada da API ajuda a evitar que o emissor seja bloqueado ou penalizado por enviar consultas repetidas sem necessidade.

Como tratar corretamente um HTTP 429?

O primeiro passo é não reenviar imediatamente. Muitas APIs informam no cabeçalho Retry-After quantos segundos o cliente deve esperar. Quando esse cabeçalho existir, ele deve ser respeitado.

Se não houver indicação, a prática recomendada é o backoff exponencial: esperar um pouco antes da primeira nova tentativa e aumentar o intervalo a cada falha seguida. Somar um pequeno valor aleatório ao tempo de espera, o chamado jitter, evita que vários processos tentem de novo exatamente no mesmo instante.

Como a requisição original pode ser repetida, é importante usar idempotência: enviar uma chave única por documento, para que uma nova tentativa nunca gere uma nota duplicada.

Qual a diferença entre HTTP 429 e uma rejeição da SEFAZ?

O HTTP 429 acontece antes de o documento chegar ao fisco. É um controle de tráfego da API, e a solução é esperar e tentar de novo, sem alterar nada no conteúdo da nota.

Uma rejeição da SEFAZ ou da prefeitura ocorre depois que o documento foi analisado e algum dado foi considerado inválido, como um CFOP incorreto ou uma inscrição estadual irregular. Nesse caso, repetir o envio sem corrigir a informação não resolve: é preciso ajustar os dados.

Como evitar receber HTTP 429 com frequência?

Uma boa estratégia é organizar as emissões em uma fila, enviando documentos em ritmo controlado em vez de disparar todos de uma vez. Em fechamentos de mês ou grandes promoções, isso evita picos desnecessários.

Outra medida é trocar consultas repetidas de status por notificações automáticas, como webhooks, em um fluxo assíncrono de emissão. Assim, o sistema não precisa perguntar a cada segundo se a nota foi autorizada: ele é avisado quando o resultado estiver pronto.

Exemplos de HTTP 429 na integração fiscal

• Um e-commerce em dia de grande promoção tenta emitir centenas de NFC-e por minuto, recebe HTTP 429 em parte das chamadas e passa a reenviá-las a partir de uma fila, respeitando o tempo indicado no cabeçalho Retry-After.
• Um ERP consultava o status de cada NF-e a cada segundo até a autorização; após receber vários HTTP 429, a equipe substituiu as consultas por webhooks e o erro deixou de ocorrer.
• Uma plataforma de serviços que emite NFS-e para muitos CNPJs no fechamento do mês aplica backoff exponencial com jitter, evitando que todos os processos tentem novamente ao mesmo tempo.
• Um desenvolvedor percebe que um laço de repetição sem pausa estava disparando a mesma requisição de download de XML continuamente, gerando HTTP 429 em sequência.