Wortic

Wortic CEP / Guias

Limite, bloqueio e cache do lado do cliente

São 60 consultas por minuto por IP, sem chave. Guardar as respostas pelo tempo que a API manda e esperar o retry-after mantém o seu sistema longe do bloqueio.

Publicado em .

Fontes oficiais: o CEP nos Correios e os códigos de município do IBGE.

Endereço quase não muda. Por isso o mesmo CEP não precisa ir à API duas vezes no mesmo dia, e é isso que mais reduz consultas.

O que a API manda

RespostaCabeçalhoO que fazer
200, o endereçopublic, max-age=86400Guarde por 24 horas
404 nao_encontradopublic, max-age=3600Guarde por 1 hora
429 limite ou bloqueadoretry-afterEspere os segundos que ele diz
403 banidoPare e fale com a Wortic

O código

export function criarCache() {
  const guardado = new Map();
  return async function cepComCache(texto) {
    const chave = limparCep(texto), agora = Date.now(), item = guardado.get(chave);
    if (item && item.vence > agora) return { ...item.valor, do_cache: true };
    const r = await fetch(`https://cep.wortic.com/cep/${chave}`);
    if (r.status === 429 || r.status === 403) return { status: r.status, espere: Number(r.headers.get("retry-after") || 60), do_cache: false };
    const idade = Number((r.headers.get("cache-control") || "").match(/max-age=(\d+)/)?.[1] || 0);
    const valor = { status: r.status, corpo: await r.json() };
    if (r.status === 200 || r.status === 404) guardado.set(chave, { valor, vence: agora + idade * 1000 });
    return { ...valor, do_cache: false };
  };
}

const cep = criarCache();
await cep("01001000");     // vai à API
await cep("01001-000");    // vem do cache: mesmo CEP, outra escrita

Quem fica abaixo de 60 consultas por minuto nunca é bloqueado. Se receber 429, espere o retry-after antes de voltar; repetir sem esperar é o que leva um IP à escada. Para volume maior, use uma chave no cabeçalho x-api-key.

Perguntas e respostas

Qual é o limite da API de CEP sem chave?

60 consultas por minuto por IP. Acima disso a resposta é 429 com o código limite e o cabeçalho retry-after em segundos.

Quando o IP é bloqueado?

Cada minuto em que o IP passa do limite 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.

Por quanto tempo posso guardar a resposta?

A resposta encontrada vem com cache-control: public, max-age=86400 (24 horas); a de CEP não encontrado, com max-age=3600 (1 hora).

Todos os guias · Documentação com exemplos em 10 linguagens · openapi.json · Versão para IA