Wortic

Wortic CNPJ / Guias

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

RespostaQuandoO que o seu código faz
402 limite_gratisPassou de 60 no minuto, ou de 2.000 no diaNo 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 bloqueadoInsistiu acima do limite do minutoPara tudo até passar o retry-after
403 banidoInsistiu depois de bloqueiosPara de vez e fala com a Wortic

A escada

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