Tratar o 402 e o retry-after sem ser bloqueado
São 60 consultas por minuto e 2.000 por dia, por IP, sem chave. Quem fica dentro desse limite nunca é bloqueado. Quem passa recebe 402 com o código limite_gratis e espera o retry-after antes de voltar. Este guia mostra a regra e o código.
Publicado em .
Fontes oficiais: o CNPJ na Receita Federal e os dados abertos do CNPJ.
A API é aberta e grátis. O limite existe para ela continuar rápida para todo mundo. Ele é simples e previsível: a resposta diz quanto esperar.
As respostas de limite
| Resposta | Quando | O que o seu código faz |
|---|---|---|
402 limite_gratis | Passou de 60 no minuto, ou de 2.000 no dia | No minuto, espera os segundos do retry-after e tenta de novo. No dia, o retry-after passa de 2 minutos: pare e avise, sem esperar até a meia-noite |
429 bloqueado | Insistiu acima do limite do minuto | Para tudo até passar o retry-after |
403 banido | Insistiu depois de bloqueios | Para de vez e fala com a Wortic |
A escada
- Cada minuto em que o IP passa do limite do minuto conta uma vez.
- Com 10 vezes, o IP fica bloqueado por 1 hora.
- Depois de 3 bloqueios de 1 hora, o seguinte é de 6 horas.
- Depois de 3 bloqueios de 6 horas, o IP é banido de vez.
- Passar do limite do dia não entra nessa conta.
O código
export async function consultar(caminho, { tentativas = 2 } = {}) {
for (let i = 0; ; i++) {
const r = await fetch("https://cnpj.wortic.com" + caminho);
if (r.status !== 402 && r.status !== 429 && r.status !== 403) return { status: r.status, corpo: await r.json() };
const corpo = await r.json();
const espera = Number(r.headers.get("retry-after") || 60);
if (r.status === 403 || corpo?.erro?.codigo === "bloqueado" || espera > 120 || i >= tentativas)
return { status: r.status, corpo }; // banido, bloqueado, limite do dia ou tentativas esgotadas: pare; tentar de novo agora só piora
await new Promise((ok) => setTimeout(ok, espera * 1000));
}
}
Dois cuidados fazem a diferença: tentar poucas vezes e nunca repetir diante de bloqueado ou banido. Um laço que repete sem esperar é o que leva um IP à escada.
O melhor jeito de não ver 402 é não pedir duas vezes a mesma coisa: veja o guia de cache.
Perguntas e respostas
Qual é o limite da API sem chave?
60 consultas por minuto e 2.000 por dia, por IP. Acima disso a resposta é HTTP 402 com o código limite_gratis e o cabeçalho retry-after em segundos: 60 no limite do minuto, e até a meia-noite de Brasília no limite do dia.
Quando o IP é bloqueado?
Cada minuto em que o IP passa do limite do minuto conta uma vez. Com 10 minutos assim, o IP fica bloqueado por 1 hora (429 bloqueado). Depois de 3 bloqueios de 1 hora, o seguinte é de 6 horas. Depois de 3 bloqueios de 6 horas, o IP é banido (403 banido). Passar do limite do dia não conta para essa escada.
Como consultar mais de 2.000 por dia?
Com uma chave no cabeçalho x-api-key: vale o limite do plano e a escada de bloqueio não se aplica.
Todos os guias · Documentação com exemplos em 10 linguagens · openapi.json · Versão para IA