Errores

Todo error tiene el mismo formato:

{
  "code": "sql_rejected",
  "message": "La consulta SQL generada fue rechazada.",
  "details": { "violations": [{ "code": "unknown_column", "params": {} }] }
}

• code es estable y en inglés. Programa contra él.
• message viene traducido al idioma resuelto (locale → Accept-Language → idioma por defecto del tenant → pt-BR) y puede mostrarse al usuario, pero su texto puede cambiar.
• details trae datos extra, que varían según el código.

Toda respuesta, de éxito o de error, trae el header X-Request-ID (req_…). Regístralo en tus logs e informalo al pedir soporte.

Códigos

HTTP	code	Significado y acción
400	end_user_required	El tenant exige end_user y la pregunta llegó sin él.
401	invalid_api_key	Header ausente, mal formado, clave inexistente o revocada. No repitas sin corregirla.
404	request_not_found	request_id desconocido, de otro tenant o no evaluable (feedback e historial).
404	not_found	La ruta no existe.
405	method_not_allowed	Método HTTP no aceptado por la ruta (consulta el header Allow).
409	schema_not_configured	El tenant aún no registró el DDL en el panel.
409	llm_not_configured	El tenant no configuró proveedor, modelo y clave de LLM.
409	unsupported_llm_provider	El proveedor guardado ya no se acepta; el administrador debe cambiarlo.
409	secret_unreadable	La clave de LLM guardada ya no se puede leer; el administrador debe registrarla de nuevo.
413	payload_too_large	Cuerpo por encima de 96 KiB.
422	invalid_request	Cuerpo o query inválidos, o campo desconocido. details.fields lista los campos.
422	invalid_end_user	end_user fuera del formato: parece un correo o un nombre, tiene espacios o es demasiado corto.
422	question_too_long	Pregunta por encima de 2.000 caracteres (details.limit).
422	invalid_max_rows	max_rows inválido.
422	prompt_too_large	El schema, el contexto y los ejemplos no caben en el prompt. Avisa al administrador.
422	no_answer	El LLM concluyó que el schema no responde a la pregunta. Pide al usuario que reformule.
422	sql_rejected	El SQL generado no pasó el SQL Guard, incluso tras la corrección automática. details.violations es una lista de {code, params} con códigos genéricos.
422	invalid_feedback	Valoración inválida en /v1/feedback.
429	rate_limited	Límite de solicitudes alcanzado. details.scope = "end_user" cuando el límite es el del usuario final. Respeta Retry-After.
500	internal_error	Error inesperado. Envía el X-Request-ID a soporte.
502	llm_error	Fallo del LLM del tenant. Consulta details.reason más abajo.
503	service_unavailable	Base de datos de la plataforma inaccesible o sobrecargada. Trae Retry-After.
503	not_ready	Servicio sin acceso a la base de datos; intenta de nuevo.

sql_rejected

Para no revelar lo que tu administrador ocultó, las tablas y columnas ocultas aparecen como unknown_table y unknown_column, y los nombres de columna nunca se devuelven. El motivo real queda en el Historial del panel. Reformular la pregunta suele resolverlo; si una pregunta legítima se rechaza con frecuencia, registra un ejemplo para ella en el panel.

llm_error y details.reason

reason	Acción
timeout, llm_unavailable, llm_rate_limited	Transitorio: intenta de nuevo con espera creciente.
invalid_llm_key, invalid_model	El administrador debe corregir la configuración de LLM en el panel.
empty_response, invalid_response	El LLM respondió algo inutilizable; reintentar o reformular.

Política de reintento sugerida

Situación	Qué hacer
429	Esperar los segundos de Retry-After antes de repetir.
502 con reason transitorio, 503	Espera exponencial (1 s, 2 s, 4 s), como máximo 3 intentos.
401, 409, 422	No repetir la misma solicitud.
Timeout de tu cliente HTTP en /v1/ask	No repetir automáticamente: cada intento gasta tokens. Deja que el usuario lo intente de nuevo.