Erros

Todo erro tem o mesmo formato:

{
  "code": "sql_rejected",
  "message": "A consulta SQL gerada foi rejeitada.",
  "details": { "violations": [{ "code": "unknown_column", "params": {} }] }
}

• code é estável e em inglês. Programe contra ele.
• message vem traduzida no idioma resolvido (locale → Accept-Language → padrão do tenant → pt-BR) e pode ser mostrada ao usuário, mas pode mudar de texto.
• details traz dados extras, que variam por código.

Toda resposta, de sucesso ou de erro, traz o header X-Request-ID (req_…). Registre-o nos seus logs e informe-o ao pedir suporte.

Códigos

HTTP	code	Significado e ação
400	end_user_required	O tenant exige end_user e a pergunta veio sem ele.
401	invalid_api_key	Header ausente, mal formado, chave inexistente ou revogada. Não repita sem corrigir.
404	request_not_found	request_id desconhecido, de outro tenant ou não avaliável (feedback e histórico).
404	not_found	Rota inexistente.
405	method_not_allowed	Método HTTP não aceito pela rota (veja o header Allow).
409	schema_not_configured	O tenant ainda não cadastrou o DDL no painel.
409	llm_not_configured	O tenant não configurou provedor, modelo e chave de LLM.
409	unsupported_llm_provider	O provedor salvo não é mais aceito; o administrador precisa trocá-lo.
409	secret_unreadable	A chave de LLM salva não pode mais ser lida; o administrador precisa cadastrá-la de novo.
413	payload_too_large	Corpo acima de 96 KiB.
422	invalid_request	Corpo ou query inválidos, ou campo desconhecido. details.fields lista os campos.
422	invalid_end_user	end_user fora do formato: parece e-mail ou nome, tem espaço ou é curto demais.
422	question_too_long	Pergunta acima de 2.000 caracteres (details.limit).
422	invalid_max_rows	max_rows inválido.
422	prompt_too_large	Schema, contexto e exemplos não cabem no prompt. Avise o administrador.
422	no_answer	A LLM concluiu que o schema não responde à pergunta. Peça para o usuário reformular.
422	sql_rejected	O SQL gerado não passou no SQL Guard, mesmo após a correção automática. details.violations é uma lista de {code, params} com códigos genéricos.
422	invalid_feedback	Avaliação inválida em /v1/feedback.
429	rate_limited	Limite de requisições atingido. details.scope = "end_user" quando o limite é o do usuário final. Respeite Retry-After.
500	internal_error	Erro inesperado. Envie o X-Request-ID ao suporte.
502	llm_error	Falha da LLM do tenant. Veja details.reason abaixo.
503	service_unavailable	Banco da plataforma inacessível ou sobrecarregado. Traz Retry-After.
503	not_ready	Serviço sem acesso ao banco; tente de novo.

sql_rejected

Para não revelar o que o seu administrador ocultou, tabelas e colunas ocultas aparecem como unknown_table e unknown_column, e nomes de coluna nunca são devolvidos. O motivo real fica no Histórico do painel. Reformular a pergunta costuma resolver; se uma pergunta legítima é rejeitada com frequência, cadastre um exemplo para ela no painel.

llm_error e details.reason

reason	Ação
timeout, llm_unavailable, llm_rate_limited	Transitório: tente de novo com backoff.
invalid_llm_key, invalid_model	O administrador precisa corrigir a configuração de LLM no painel.
empty_response, invalid_response	A LLM respondeu algo inutilizável; tentar de novo ou reformular.

Política de retry sugerida

Situação	O que fazer
429	Aguardar os segundos de Retry-After antes de repetir.
502 com reason transitório, 503	Backoff exponencial (1 s, 2 s, 4 s), no máximo 3 tentativas.
401, 409, 422	Não repetir a mesma requisição.
Timeout do seu cliente HTTP em /v1/ask	Não repetir automaticamente: cada tentativa gasta tokens. Deixe o usuário tentar de novo.