Estou recebendo diversos retornos “429 Too Many Requests” ao consultar o endpoint:
https://adn.nfse.gov.br/contribuintes/DFe/{nsu}
Poderiam, por favor, esclarecer o rate limit e as regras de validação aplicadas?
Dúvidas objetivas
A limitação é controlada por IP, por certificado digital ou por outro critério?
Qual é o volume máximo de solicitações permitido (por minuto/hora/dia)?
Há janelas deslizantes ou burst limits (p. ex., X requisições em Y segundos)?
Existem códigos de resposta ou headers (ex.: X-RateLimit-Remaining, Retry-After) que orientem o reenvio?
Cenário
Operamos um SaaS com 200k+ CNPJs consultando o DFe.
Mesmo consultando por faixa de NSU (inicial → final) diária (1x por CNPJ a cada 24h), o número de requisições varia conforme a disponibilidade de documentos e a quantidade de CNPJs, concentrando um volume relevante de chamadas a partir do mesmo IP.
Ainda não há um limite, mas, quando são várias requisições do mesmo CNPJ, por haver vários documentos, estão dando um time de 1 minuto a cada 3 buscas de lote ou quando ocorre o erro.
Em cenários de rate limit, é comum que as APIs retornem, além do status 429, alguns cabeçalhos HTTP padrão (como Retry-After, X-Retry-In ou headers específicos) informando quanto tempo o cliente deve aguardar antes de realizar uma nova tentativa.
O ideal, nesse caso, é que a aplicação leia esses headers e ajuste dinamicamente o tempo de espera, em vez de trabalhar com intervalos fixos. Isso torna a integração mais resiliente e preparada para eventuais mudanças no controle de carga do lado do servidor.
Vocês saberiam informar se a API do ADN retorna algum header indicando o tempo de espera quando ocorre o 429?
Amostra foi feita para um único município e um único mês de competência, varrendo todos os “cTribNac” e respectivos desdobramentos (“000” e/ou incrementais “001”, “002”…).
Foram 1.335 requisições em cerca de 87 segundos. Neste teste não houve nenhum evento 429 e atingiu média de 65ms/request. Teste foi feito à noite, 21:20:00, de 21/01/2026.
Para evitar prejudicar o certificado digital utilizado não forcei volume maior de requisições (que eventualmente poderia atingir o 429).
Seguem gráficos para eventual referência adicional.
Me perdoe.
No automático eu respondi, mas a minha resposta era para o Too Many Request.
Eu não entendi exatamente onde este erro tem ocorrido.
No endpoint de busca das alíquotas quando você faz o que sugeri de a cada código buscar de 000 a 999 para ver quais desdobros o município tem?
Me contextualiza melhor, pois estou sem tempo de analisar aprofundadamente, só as reuniões tem me tomado umas 3 horas por dia.
Meu cargo na Federação é Pró-Bonus e no GT Piloto também, então peço que me auxilie contextualizando melhor.
A minha dúvida era sobre rate limit no endpoint /aliquota, cujo volume de resultados atinge ordem de milhões de resultados (nº de municípios x nº de alíquotas). Mas não houve erro too many requests: fiz inicialmente sem paralelismo (resultados nos gráficos acima) e depois com 64 chamadas paralelas, que também transcorreu sem erro (cerca de 1,5 mi de resultados para todos os municípios do Brasil).
Uma dúvida: preciso pesquisar o intervalo completo até 999? O conjunto de códigos municipais pode ser descontínuo?
Hoje estou considerando que são contínuos. Ou seja, ao fazer a pesquisa de forma sequencial e atingir um código que dê erro 404 (não encontrado) então estou considerando que dali em diante não haverá mais códigos em uso.
Exemplo: iniciei a pesquisa em 001 e obtive resultados válidos até o código 015, e no código 016 retornou erro. Neste caso então eu ignoro o intervalo seguinte (016 a 999), nem faço consulta deles.
Tenho sugestão complementar: endpoint retornando este conjunto completo (todos códigos nacionais consolidados, com respectivos desdobros, descrição, alíquota, competência) num resultado com paginação. O motivo disto é que precisamos coletar estes dados para popular as bases de nossos sistemas/ERPs.
Hoje há ~100 códigos nacionais (itens e subitens da Lei 116), e tipicamente um município tem cerca de <700 desdobros. Se utilizar paginação de 100 resultados, seriam <10 requisições. Mas se mantiver uma consulta para cada código nacional seriam ~100 requisições (e respectivas paginações quando passar do limite).
Alguma novidade em relação a essa API que você comentou? Estamos com cada vez mais empresas precisando deste serviço. Como desenvolvedores de software precisamos disso para apresentar ao cliente as opções sem que ele precise acessar o portal nacional para isso.
