Erros

Erros voltam como códigos de máquina em inglês, sempre no formato { "error": { "code": "...", "details": { … } } }. Esta tabela é a tradução: o que cada código significa e o que fazer.

Códigos da API REST

HTTP	Código	O que significa	O que fazer
401	`invalid_key`	Chave ausente, errada, expirada ou revogada.	Confira o cabeçalho `Authorization: Bearer`; crie outra chave em Chaves & Uso se necessário.
402	`quota_exceeded`	O limite mensal de linhas do plano acabou.	Aguarde a virada do mês ou fale com o suporte sobre o plano. `details` traz o uso.
403	`out_of_scope`	A chave não tem permissão para este recurso, operação ou coluna.	Peça ao administrador uma chave com o domínio necessário.
403	`tenant_suspended`	A organização está suspensa ou cancelada.	Fale com o suporte.
404	`not_found`	Caminho inexistente.	Confira o path na lista de endpoints.
422	`invalid_param` · `invalid_filter` · `invalid_metric` · `invalid_sort` · `invalid_bucket` · `param_out_of_range`	Algum parâmetro está malformado ou não é permitido — `details` nomeia o campo.	Compare com a página do endpoint e a sintaxe de consulta.
429	`rate_limited`	Requisições demais neste minuto para esta chave.	Espere o próximo minuto. Não há cabeçalho `Retry-After`; o limite vem em `details.limit`.
500	`internal`	Erro interno (sem detalhes, de propósito).	Tente de novo; persistindo, suporte@openthor.dev.
503	`unavailable`	Plano de dados indisponível (configuração de deploy).	Tente em instantes; persistindo, suporte.

Exemplo

JSON

{ "error": { "code": "invalid_filter", "details": { "field": "municipality_code" } } }

Erros no MCP (assistentes de IA)

No MCP as mensagens também são em inglês e mais curtas — o assistente costuma explicá-las sozinho, mas para conferência:

Mensagem	O que significa
`invalid or non-MCP key`	Credencial inválida para o MCP (ou sem permissão de MCP).
`out of scope: mcp:sales`	Sua credencial não tem esse domínio — a ferramenta nem deveria aparecer na sua lista.
`query rejected: <código>`	A consulta foi recusada — o código é um dos da tabela acima (ex.: `invalid_param`).
`unknown tool: <nome>`	Ferramenta inexistente (versão antiga da lista no cliente — reconecte).

Dica

“Conectado, mas 0 ferramentas” quase nunca é erro de rede — é escopo/permissão da sua credencial. Veja Problemas de conexão.

Esta página ajudou? Conte para a gente — lemos tudo.