Errores HTTP y seguridad de la clave de API
En esta página
Actualizado el 3 de noviembre de 2026, según las páginas Text to Speech y Rate limits de xAI: texto limitado a 60.000 caracteres, el error 404 (voz desconocida) y los límites de tasa por nivel. Fuentes: Text to Speech · Rate limits.
Gestión de errores y protección de credenciales
En producción, tu aplicación debe gestionar los errores de la API TTS con elegancia y, sobre todo, nunca exponer tu clave de API en el cliente. Esta lección cubre códigos de error, estrategias de reintento y la arquitectura de proxy backend.
Códigos de error HTTP
La API TTS devuelve códigos de error HTTP estándar. Así es como debes reaccionar ante cada uno.
400: Bad Request
El servidor no ha podido procesar tu solicitud. Causas habituales:
- Texto vacío o texto superior a 60.000 caracteres
- Un códec inválido (una errata en el nombre)
- Una frecuencia de muestreo no compatible
if response.status_code == 400:
error = response.json()
print(f"Solicitud inválida: {error}")
# Corrige los parámetros e inténtalo de nuevo
No reintentes automáticamente un error 400: el problema reside en tu solicitud, no en el servidor. Corrige primero los parámetros.
401: Unauthorized
La clave de API no es válida, ha caducado o falta:
if response.status_code == 401:
raise AuthenticationError("Clave de API inválida o caducada")
Comprueba que:
- La cabecera
Authorizationestá presente - El formato es
Bearer xai-...(con un espacio después de Bearer) - La clave no ha sido revocada en la consola de xAI
404: Not Found
El ID de voz es desconocido: compruébalo con GET /v1/tts/voices para una voz integrada, o GET /v1/custom-voices para una voz personalizada. Al igual que un 400, un 404 no desaparecerá si reintentas la operación.
429: Too Many Requests
Has superado un límite de tasa: en el nivel de entrada, 50 solicitudes por segundo y 100 sesiones simultáneas para TTS según la página Rate limits, y 50 sesiones WebSocket simultáneas por equipo según la página Text to Speech. xAI recomienda reintentar con retroceso exponencial:
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 5))
await asyncio.sleep(retry_after)
# Inténtalo de nuevo
Implementa un retroceso exponencial para los errores 429:
async def request_with_backoff(url, payload, headers, max_retries=5):
for attempt in range(max_retries):
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
return response
if response.status_code == 429:
wait = min(2 ** attempt + random.random(), 60)
print(f"Límite de tasa alcanzado. Esperando {wait:.1f}s")
await asyncio.sleep(wait)
continue
if response.status_code >= 500:
wait = min(2 ** attempt + random.random(), 30)
await asyncio.sleep(wait)
continue
# Error del cliente (400, 401): no reintentar
response.raise_for_status()
raise Exception("Fallo tras 5 intentos")
500 / 503: Server Error
El servidor tiene un problema temporal. Reintenta con retroceso:
if response.status_code in (500, 503):
# Reintentar con retroceso exponencial
pass
Los errores 503 suelen deberse a una sobrecarga temporal. Normalmente se resuelven en unos pocos segundos.
Nunca expongas la clave de API en el cliente
Esta es la regla de seguridad más importante. Si tu clave de API es visible en el JavaScript del navegador, cualquiera puede:
- Utilizar tu cuota gratuitamente
- Generar cargos en tu cuenta
- Acceder a todos los puntos finales de la API de xAI con tu clave
Arquitectura de proxy backend
La solución es intermediar las llamadas TTS a través de tu propio backend:
Navegador -> Tu backend -> API de xAI
(sin clave) (clave API) (TTS)
Ejemplo en Express.js
const express = require("express");
const app = express();
app.post("/api/tts", async (req, res) => {
const { text, voice_id, language } = req.body;
// Validación en el servidor
if (!text || text.length > 60000) {
return res.status(400).json({ error: "Texto inválido" });
}
const response = await fetch("https://api.x.ai/v1/tts", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.XAI_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ text, voice_id, language })
});
if (!response.ok) {
return res.status(response.status).json({
error: "Error de TTS"
});
}
// Pasar el audio al cliente
res.set("Content-Type", response.headers.get("Content-Type"));
const buffer = await response.arrayBuffer();
res.send(Buffer.from(buffer));
});
Ejemplo en FastAPI (Python)
from fastapi import FastAPI, HTTPException
from fastapi.responses import Response
import httpx
app = FastAPI()
@app.post("/api/tts")
async def proxy_tts(text: str, voice_id: str = "eve", language: str = "en"):
if len(text) > 60000:
raise HTTPException(400, "Texto demasiado largo")
async with httpx.AsyncClient() as client:
response = await client.post(
"https://api.x.ai/v1/tts",
headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
json={"text": text, "voice_id": voice_id, "language": language}
)
if response.status_code != 200:
raise HTTPException(response.status_code, "Error de TTS")
return Response(
content=response.content,
media_type=response.headers["content-type"]
)
Proxy WebSocket
Para TTS WebSocket, tu backend debe retransmitir mensajes entre el cliente y la API de xAI:
const WebSocket = require("ws");
wss.on("connection", (clientWs) => {
const xaiWs = new WebSocket(
"wss://api.x.ai/v1/tts?language=en&voice=eve",
{ headers: { Authorization: `Bearer ${process.env.XAI_API_KEY}` } }
);
// Retransmitir cliente -> xAI
clientWs.on("message", (msg) => xaiWs.send(msg));
// Retransmitir xAI -> cliente
xaiWs.on("message", (msg) => clientWs.send(msg));
// Gestionar cierre
clientWs.on("close", () => xaiWs.close());
xaiWs.on("close", () => clientWs.close());
});
Moderación fail-open
La API TTS ejecuta la moderación de contenido de forma asíncrona. Esto significa que la moderación no bloquea la solicitud: el audio se genera y se devuelve incluso si la moderación no ha finalizado su análisis.
Si el contenido se marca como inapropiado, el informe llega a posteriori. Por tanto, tu aplicación debería ejecutar su propia moderación aguas arriba si es necesario.
Puntos clave
- 400 = error de parámetro (no reintentar; corregir la solicitud)
- 401 = clave de API inválida (comprobar la cabecera Authorization)
- 429 = límite de tasa alcanzado (retroceso exponencial)
- 500/503 = error temporal del servidor (reintentar con retroceso)
- Nunca expongas la clave de API en el código del cliente
- Intermedia todas las llamadas TTS a través de tu backend
- La moderación es fail-open: añade tu propio filtrado si es necesario