Ir al contenido principal
Español— Elegir un idioma
Menú

Errores HTTP y seguridad de la clave de API

Lección 13 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Gestión de errores y protección de credenciales
  2. Códigos de error HTTP
  3. Nunca expongas la clave de API en el cliente
  4. Moderación fail-open
  5. Puntos clave

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 Authorization está 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