Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

HTTP-Fehler und Sicherheit von API-Schlüsseln

Lektion 13 von 14 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Fehlerbehandlung und Schutz Ihrer Zugangsdaten
  2. HTTP-Fehlercodes
  3. API-Schlüssel niemals im Client aussetzen
  4. Fail-open-Moderation
  5. Kernaussagen

Aktualisiert am 3. November 2026, basierend auf den xAI-Seiten Text to Speech und Rate limits: Textbegrenzung auf 60.000 Zeichen, Fehler 404 (unbekannte Stimme) und Rate Limits pro Tarifstufe. Quellen: Text to Speech · Rate limits.

Fehlerbehandlung und Schutz Ihrer Zugangsdaten

In der Produktion muss Ihre Anwendung TTS-API-Fehler angemessen verarbeiten und vor allem niemals Ihren API-Schlüssel im Client aussetzen. Diese Lektion behandelt Fehlercodes, Retry-Strategien und die Backend-Proxy-Architektur.

HTTP-Fehlercodes

Die TTS-API gibt standardmäßige HTTP-Fehlercodes zurück. Hier ist die Reaktion auf jeden davon.

400: Bad Request

Der Server konnte Ihre Anfrage nicht verarbeiten. Häufige Ursachen:

  • Leerer Text oder Text über 60.000 Zeichen
  • Ein ungültiger Codec (ein Tippfehler im Namen)
  • Eine nicht unterstützte Abtastfrequenz
if response.status_code == 400:
    error = response.json()
    print(f"Ungültige Anfrage: {error}")
    # Parameter korrigieren und erneut versuchen

Wiederholen Sie einen 400-Fehler nicht automatisch: Das Problem liegt in Ihrer Anfrage, nicht auf dem Server. Korrigieren Sie zuerst die Parameter.

401: Unauthorized

Der API-Schlüssel ist ungültig, abgelaufen oder fehlt:

if response.status_code == 401:
    raise AuthenticationError("Ungültiger oder abgelaufener API-Schlüssel")

Prüfen Sie Folgendes:

  • Das Authorization-Header ist vorhanden
  • Das Format lautet Bearer xai-... (mit einem Leerzeichen nach Bearer)
  • Der Schlüssel wurde im xAI-Konsole nicht widerrufen

404: Not Found

Die Voice-ID ist unbekannt: Prüfen Sie sie mit GET /v1/tts/voices für eine integrierte Stimme oder GET /v1/custom-voices für eine benutzerdefinierte Stimme. Wie bei einem 400-Fehler wird sich ein 404-Fehler nicht durch erneutes Versuchen auflösen.

429: Too Many Requests

Sie haben ein Rate Limit überschritten: Auf der Entry-Tier-Stufe sind es 50 Anfragen pro Sekunde und 100 gleichzeitige Sitzungen für TTS laut der Seite Rate limits, sowie 50 gleichzeitige WebSocket-Sitzungen pro Team laut der Seite Text to Speech. xAI empfiehlt das Wiederversuchen mit exponentiellem Backoff:

if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 5))
    await asyncio.sleep(retry_after)
    # Erneut versuchen

Implementieren Sie exponentiellen Backoff für 429-Fehler:

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"Rate limit erreicht. Warten {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

        # Client-Fehler (400, 401): Nicht wiederholen
        response.raise_for_status()

    raise Exception("Nach 5 Versuchen fehlgeschlagen")

500 / 503: Server Error

Der Server hat ein vorübergehendes Problem. Wiederholen Sie mit Backoff:

if response.status_code in (500, 503):
    # Mit exponentiellem Backoff wiederholen
    pass

503-Fehler werden oft durch vorübergehende Überlastung verursacht. Sie lösen sich in der Regel innerhalb weniger Sekunden auf.

API-Schlüssel niemals im Client aussetzen

Dies ist die wichtigste Sicherheitsregel. Wenn Ihr API-Schlüssel im JavaScript des Browsers sichtbar ist, kann jeder:

  • Ihren Kontingentverbrauch kostenlos nutzen
  • Kosten auf Ihrem Konto verursachen
  • Alle xAI-API-Endpunkte mit Ihrem Schlüssel erreichen

Backend-Proxy-Architektur

Die Lösung besteht darin, TTS-Aufrufe über Ihren eigenen Backend zu leiten:

Browser -> Ihr Backend -> xAI API
 (kein Schlüssel)    (API-Schlüssel)      (TTS)

Express.js-Beispiel

const express = require("express");
const app = express();

app.post("/api/tts", async (req, res) => {
  const { text, voice_id, language } = req.body;

  // Serverseitige Validierung
  if (!text || text.length > 60000) {
    return res.status(400).json({ error: "Ungültiger Text" });
  }

  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: "TTS-Fehler"
    });
  }

  // Audio an den Client weiterleiten
  res.set("Content-Type", response.headers.get("Content-Type"));
  const buffer = await response.arrayBuffer();
  res.send(Buffer.from(buffer));
});

FastAPI-Beispiel (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, "Text zu lang")

    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, "TTS-Fehler")

    return Response(
        content=response.content,
        media_type=response.headers["content-type"]
    )

WebSocket-Proxy

Für TTS-WebSocket muss Ihr Backend Nachrichten zwischen Client und xAI-API weiterleiten:

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}` } }
  );

  // Client -> xAI weiterleiten
  clientWs.on("message", (msg) => xaiWs.send(msg));

  // xAI -> Client weiterleiten
  xaiWs.on("message", (msg) => clientWs.send(msg));

  // Schließen behandeln
  clientWs.on("close", () => xaiWs.close());
  xaiWs.on("close", () => clientWs.close());
});

Fail-open-Moderation

Die TTS-API führt Inhaltsmoderation asynchron durch. Das bedeutet, die Moderation blockiert die Anfrage nicht: Das Audio wird generiert und zurückgegeben, auch wenn die Moderation ihre Analyse noch nicht abgeschlossen hat.

Wenn Inhalte als unangemessen markiert werden, kommt der Bericht nachträglich. Daher sollte Ihre Anwendung bei Bedarf ihre eigene Moderation upstream durchführen.

Kernaussagen

  • 400 = Parameterfehler (nicht wiederholen; Anfrage korrigieren)
  • 401 = ungültiger API-Schlüssel (Header Authorization prüfen)
  • 429 = Rate limit erreicht (exponentieller Backoff)
  • 500/503 = vorübergehender Serverfehler (mit Backoff wiederholen)
  • API-Schlüssel niemals im Client-Code aussetzen
  • Alle TTS-Aufrufe über Ihr Backend leiten
  • Moderation ist fail-open: Fügen Sie bei Bedarf eigene Filter hinzu