Limites e erros

O limite de uso, o formato das respostas de erro e como o seu site deve reagir a cada situação.

#Limite de uso

Cada chave pode fazer 60 requisições por minuto. Passou disso, a API responde 429 até a janela de um minuto virar. O limite protege a sua imobiliária de abuso e vale por chave, não por visitante.

Para um site comum, 60 por minuto é muito: o segredo é não repassar cada visita do público para a API. Guarde (faça cache) no servidor do site as respostas que mudam pouco:

Dado	Cache sugerido
Dados da imobiliária e banners	10 a 60 minutos
Cidades e bairros (`/localizacoes`)	10 a 30 minutos
Lista de imóveis e página de um imóvel	1 a 5 minutos
Envio de contato (`POST /leads`)	Nunca guardar em cache

#Formato dos erros

Toda resposta de erro traz um status HTTP e um JSON com o texto do problema em error:

401 Unauthorized

{
  "error": "Chave de API inválida ou revogada."
}

#Códigos de status

Status	Quando acontece	Texto de exemplo
`400`	Em `POST /leads`, faltou `nome` ou `telefone`.	“Nome e telefone/WhatsApp são obrigatórios.”
`401`	Chave ausente, inválida ou revogada.	“Chave de API inválida ou revogada.”
`404`	Imóvel, vitrine ou imobiliária não encontrado (ou link expirado).	“Imóvel não encontrado.”
`429`	Mais de 60 requisições em 1 minuto com a mesma chave.	“Limite de requisições excedido. Tente novamente em instantes.”
`500`	Erro inesperado do nosso lado. Tente de novo; se persistir, fale com o suporte.	“Erro ao buscar imóveis.”
`503`	Serviço temporariamente indisponível.	“Serviço indisponível.”

#Como reagir

400: mostre ao visitante que nome e telefone são necessários. Valide no formulário antes de enviar.
401: problema de configuração do seu servidor. Confira a chave e se ela não foi revogada. Não repita a chamada em loop.
404: o imóvel saiu do ar ou o link expirou. Mostre uma página amigável e sugira outros imóveis.
429: espere alguns segundos e tente de novo, e reveja o cache do site.
500 e 503: tente novamente com espera crescente (1 s, 2 s, 4 s) e, se continuar, exiba o que estiver em cache.

JavaScript

async function chamarZariv(caminho, tentativas = 3) {
  for (let i = 0; i < tentativas; i++) {
    const r = await fetch("https://web.zariv.com.br/api/public/v1" + caminho, {
      headers: { Authorization: `Bearer ${process.env.ZARIV_API_KEY}` },
    });
    if (r.ok) return r.json();
    if (r.status === 429 || r.status >= 500) {
      await new Promise((ok) => setTimeout(ok, 1000 * 2 ** i)); // espera crescente
      continue;
    }
    throw new Error(`Zariv respondeu ${r.status}`); // 4xx: não adianta repetir
  }
  throw new Error("Zariv indisponível");
}

Python

import os, time, requests

def chamar_zariv(caminho, tentativas=3):
    for i in range(tentativas):
        r = requests.get(
            "https://web.zariv.com.br/api/public/v1" + caminho,
            headers={"Authorization": f"Bearer {os.environ['ZARIV_API_KEY']}"},
            timeout=15,
        )
        if r.ok:
            return r.json()
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(2 ** i)  # espera crescente
            continue
        r.raise_for_status()  # 4xx: não adianta repetir
    raise RuntimeError("Zariv indisponível")