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).
