HTTP-Fehler und Sicherheit von API-Schlüsseln
Auf dieser Seite
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
Authorizationprü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