Cuando una petición falla, Semantara devuelve un JSON con un campo error_code estable (además
del detail legible, cuyo texto puede variar por idioma). Programa contra error_code, no contra
detail.
{
"detail": "API key inválida",
"error_code": "AUTH_003"
}
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 o revisa el límite de tu plan.
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_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_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.