Errors

O payload sempre inclui request_id e um code legível.

{
  "request_id": "req_01HX...",
  "code": "invalid_query",
  "message": "Query ampla demais para o plano atual.",
  "details": { "hint": "Adicione UF + CNAE para reduzir o escopo." }
}

Códigos comuns

• 401/403: API key inválida/inativa
• 422: query ampla ou inválida
• 429: rate limit/quota
• 500: erro interno

Exemplos

422 — Query ampla

{
  "request_id": "req_01HX...",
  "code": "invalid_query",
  "message": "Query ampla demais.",
  "details": { "hint": "Adicione UF + CNAE para reduzir o escopo." }
}

429 — Rate limit

{
  "request_id": "req_01HX...",
  "code": "rate_limited",
  "message": "Limite de requests excedido.",
  "details": { "retry_after_seconds": 30 }
}

401/403 — Autenticação

{
  "request_id": "req_01HX...",
  "code": "unauthorized",
  "message": "API key inválida ou sem permissão."
}

Common fixes

• Confira Authorization: Bearer <API_KEY>.
• Reduza a query com UF + CNAE.
• Respeite rate limit e faça retry com backoff.
• Verifique CORS (Studio usa chamadas diretas do browser).