Códigos de error

Cuando una petición falla, Semantara devuelve un código estable que identifica el error. Programa contra el código, no contra el texto del mensaje — el texto puede variar por idioma; el código no cambia.

El sobre del error depende de dónde se origina:

Autenticación y límites (AUTH_*) y el tamaño del cuerpo (VAL_004) se validan antes de procesar la petición, y llegan así:

{
  "detail": "API key inválida",
  "error_code": "AUTH_003"
}

Todo lo demás (validación del contenido, capacidades, proveedor, sistema) usa el sobre estándar de OpenAI — el mismo que tu SDK ya sabe leer:

{
  "error": {
    "message": "Function/tool calling is not yet supported by this gateway",
    "type": "invalid_request_error",
    "code": "LLM_009"
  }
}

Con el SDK de OpenAI, el código queda accesible en la excepción (por ejemplo, e.code). En streaming, si el error ocurre después de abrir la conexión, llega como un evento error dentro del propio stream.

Idioma del mensaje

El código no cambia nunca; el texto sí. Se determina así:

El idioma de tu cuenta (el que configuraste en la Consola). Es el que manda.
Si tu cuenta no tiene idioma definido, el header Accept-Language de la petición.
Si no hay ninguno de los dos, inglés.

Los errores de autenticación (AUTH_001, AUTH_002, AUTH_003, AUTH_010) son la excepción: se resuelven solo por Accept-Language, porque ocurren antes de saber de quién es la key — todavía no hay cuenta a la que consultarle su idioma.

Autenticación

Código	HTTP	Significado	Qué hacer
`AUTH_001`	401	Falta el header `Authorization`.	Envía `Authorization: Bearer px_live_...`.
`AUTH_002`	401	Formato de key inválido.	La key de servicio empieza con `px_live_`. Revisa que no esté truncada.
`AUTH_003`	401	Key inválida, inexistente o revocada.	Verifica la key; si la revocaste, genera una nueva en la Consola.
`AUTH_004`	429	Superaste el límite de peticiones por minuto de la key.	Reduce el ritmo de peticiones o distribúyelas en el tiempo.
`AUTH_005`	403	Esta ruta requiere una key de servicio.	Usa una key `px_live_` de servicio, no una de administración.
`AUTH_010`	429	Demasiados intentos fallidos desde tu IP; bloqueo temporal.	Espera unos minutos antes de reintentar.

Validación de la petición

Código	HTTP	Significado	Qué hacer
`VAL_001`	400	`messages` vacío o mal formado.	Envía al menos un mensaje con `role` y `content`.
`VAL_002`	400	`role` inválido en un mensaje.	Usa `system`, `user` o `assistant`.
`VAL_003`	400	Falta `content` en un mensaje.	Cada mensaje necesita `content`.
`VAL_004`	413	El cuerpo de la petición supera 1 MB.	Acorta el historial o el contenido.

Proveedor de IA

Código	HTTP	Significado	Qué hacer
`LLM_003`	400	La key no tiene un proveedor configurado.	Conecta un proveedor a esa key en la Consola.
`LLM_004`	400	Modelo o proveedor no soportado.	Usa `proxy/auto` o un modelo de un proveedor soportado.
`LLM_012`	400	Pediste un modelo explícito que ninguno de tus proveedores conectados puede servir (p. ej. un modelo de Anthropic teniendo solo una key de OpenAI).	Conecta el proveedor dueño de ese modelo, o pide un modelo de un proveedor que ya tengas (o usa `proxy/auto`).
`LLM_009`	400	La petición incluye `tools` o `tool_choice` (function calling), aún no soportado.	Quita `tools`/`tool_choice`. Si tu framework los inyecta por defecto (agentes, LangChain), desactívalos en las rutas que pasan por Semantara.
`LLM_010`	400	La petición incluye `response_format` (salida estructurada / JSON mode), aún no soportado.	Quita `response_format`. Si necesitas JSON, pídelo en el prompt y valida el resultado en tu código.
`LLM_011`	400	La petición pide varias respuestas (`n` > 1). No soportado por diseño.	Envía `n: 1` u omítelo. Si necesitas variantes, haz peticiones separadas.
`LLM_001`	5xx	Error al llamar a OpenAI.	Suele ser transitorio; reintenta. Si persiste, revisa tu clave de OpenAI.
`LLM_002`	5xx	Error al llamar a Anthropic.	Suele ser transitorio; reintenta. Si persiste, revisa tu clave de Anthropic.
`LLM_008`	5xx	Error al llamar a Gemini.	Suele ser transitorio; reintenta. Si persiste, revisa tu clave de Gemini.
`LLM_013`	503	El modelo base del enrutamiento automático no está disponible en este momento para tu proveedor. Tu petición no tiene nada de malo: es una indisponibilidad nuestra, y no te servimos otro modelo en su lugar.	Reintenta más tarde. Si necesitas continuar de inmediato, puedes pedir un modelo concreto por nombre — pero no es obligatorio.
`LLM_007`	500	Error interno al enrutar.	Reintenta; si persiste, contáctanos.

Credenciales y sistema

Código	HTTP	Significado	Qué hacer
`ENC_001`	500	No se pudieron procesar las credenciales del proveedor.	Vuelve a guardar la clave del proveedor en la Consola.
`DB_001`	500	Error temporal del servicio.	Reintenta en unos momentos.

Buenas prácticas

Reintenta los 5xx y AUTH_004/AUTH_010 con espera incremental (backoff).
No reintentes los 4xx de validación (VAL_*) ni AUTH_001/002/003: son errores de la petición o de la credencial; corrígelos antes de reenviar. Tampoco los rechazos de capacidad (LLM_009–LLM_011): la petición debe cambiar antes de reenviarse.