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
| Resposta | Cabeçalho | O que fazer |
|---|---|---|
| 200, o endereço | public, max-age=86400 | Guarde por 24 horas |
404 nao_encontrado | public, max-age=3600 | Guarde por 1 hora |
429 limite ou bloqueado | retry-after | Espere os segundos que ele diz |
403 banido | Pare 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