Erros comuns

401 / 403 — Autenticação

Sintoma: resposta authentication_required ou authentication_invalid.

Causas comuns:

• API key ausente.
• API key inválida ou desativada.

Como resolver:

• Verifique o header Authorization: Bearer <API_KEY>.
• Gere/rotacione a chave no console.

422 — Spec inválido / query ampla

Sintoma: validation_error ou query_too_broad.

Causas comuns:

• Falta de recorte geográfico.
• CNAE inválido.

Como resolver:

• Adicione uf_any_of ou municipality_ibge_any_of.
• Revise o formato do CNAE (0000-0/00).

429 — Rate limit

Sintoma: rate_limit_exceeded com header Retry-After.

Como resolver:

• Aplique backoff e tente novamente.
• Veja Recuperar de rate limit.

503 — Serviço indisponível

Sintoma: service_unavailable.

Como resolver:

• Tente novamente mais tarde.
• Se persistir, entre em contato.