HTTP-fouten en beveiliging van API-sleutels
Op deze pagina
Bijgewerkt op 3 november 2026, gebaseerd op de xAI-pagina’s Text to Speech en Rate limits: tekst beperkt tot 60.000 tekens, de 404-fout (onbekende stem) en tarieflimieten per niveau. Bronnen: Text to Speech · Rate limits.
Fouten afhandelen en uw inloggegevens beschermen
In een productieomgeving moet uw applicatie TTS-API-fouten correct afhandelen en mag uw API-sleutel nooit aan de clientkant worden blootgesteld. Deze les behandelt foutcodes, strategieën voor opnieuw proberen en de architectuur van een backend-proxy.
HTTP-foutcodes
De TTS-API retourneert standaard HTTP-foutcodes. Hier leest u hoe u op elk type moet reageren.
400: Bad Request
De server kon uw verzoek niet verwerken. Veelvoorkomende oorzaken:
- Lege tekst of tekst langer dan 60.000 tekens
- Een ongeldige codec (een typefout in de naam)
- Een niet-ondersteunde sample rate
if response.status_code == 400:
error = response.json()
print(f"Invalid request: {error}")
# Fix the parameters and try again
Probeer een 400-fout niet automatisch opnieuw: het probleem ligt in uw verzoek, niet bij de server. Los eerst de parameters op.
401: Unauthorized
De API-sleutel is ongeldig, verlopen of ontbreekt:
if response.status_code == 401:
raise AuthenticationError("Invalid or expired API key")
Controleer het volgende:
- De
Authorization-header is aanwezig - De indeling is
Bearer xai-...(met een spatie na Bearer) - De sleutel is niet ingetrokken in de xAI-console
404: Not Found
De stem-ID is onbekend: controleer deze met GET /v1/tts/voices voor een ingebouwde stem, of GET /v1/custom-voices voor een aangepaste stem. Net als bij een 400 verdwijnt een 404 niet door opnieuw te proberen.
429: Too Many Requests
U heeft een tarieflimiet overschreden: op het instapniveau geldt een limiet van 50 verzoeken per seconde en 100 gelijktijdige sessies voor TTS volgens de pagina Rate limits, en 50 gelijktijdige WebSocket-sessies per team volgens de pagina Text to Speech. xAI raadt aan opnieuw te proberen met exponentiële backoff:
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 5))
await asyncio.sleep(retry_after)
# Try again
Implementeer exponentiële backoff voor 429-fouten:
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 limited. Waiting {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 error (400, 401): don't retry
response.raise_for_status()
raise Exception("Failed after 5 attempts")
500 / 503: Server Error
De server heeft een tijdelijk probleem. Probeer het opnieuw met backoff:
if response.status_code in (500, 503):
# Retry with exponential backoff
pass
503-fouten worden vaak veroorzaakt door tijdelijke overbelasting. Ze zijn meestal binnen enkele seconden verholpen.
Stel de API-sleutel nooit bloot aan de client
Dit is de belangrijkste beveiligingsregel. Als uw API-sleutel zichtbaar is in de JavaScript van de browser, kan iedereen:
- Uw quota gratis gebruiken
- Kosten op uw account laten oplopen
- Toegang krijgen tot elk xAI API-eindpunt met uw sleutel
Architectuur van een backend-proxy
De oplossing is om TTS-aanroepen via uw eigen backend te proxyen:
Browser -> Your backend -> xAI API
(no key) (API key) (TTS)
Voorbeeld met Express.js
const express = require("express");
const app = express();
app.post("/api/tts", async (req, res) => {
const { text, voice_id, language } = req.body;
// Server-side validation
if (!text || text.length > 60000) {
return res.status(400).json({ error: "Invalid 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 error"
});
}
// Pass the audio on to the client
res.set("Content-Type", response.headers.get("Content-Type"));
const buffer = await response.arrayBuffer();
res.send(Buffer.from(buffer));
});
Voorbeeld met 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, "Text too long")
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 error")
return Response(
content=response.content,
media_type=response.headers["content-type"]
)
WebSocket-proxy
Voor TTS via WebSocket moet uw backend berichten doorsturen tussen de client en de xAI-API:
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}` } }
);
// Relay client -> xAI
clientWs.on("message", (msg) => xaiWs.send(msg));
// Relay xAI -> client
xaiWs.on("message", (msg) => clientWs.send(msg));
// Handle closing
clientWs.on("close", () => xaiWs.close());
xaiWs.on("close", () => clientWs.close());
});
Fail-open moderatie
De TTS-API voert contentmoderatie asynchroon uit. Dit betekent dat moderatie het verzoek niet blokkeert: de audio wordt gegenereerd en geretourneerd, zelfs als de moderatie de analyse nog niet heeft voltooid.
Als content als ongepast wordt gemarkeerd, komt het rapport achteraf. Uw applicatie moet daarom indien nodig zelf moderatie upstream uitvoeren.
Belangrijkste punten
- 400 = een parameterfout (niet opnieuw proberen; pas het verzoek aan)
- 401 = een ongeldige API-sleutel (controleer de Authorization-header)
- 429 = tarieflimiet overschreden (exponentiële backoff)
- 500/503 = een tijdelijke serverfout (opnieuw proberen met backoff)
- Stel de API-sleutel nooit bloot in clientcode
- Proxy alle TTS-aanroepen via uw backend
- Moderatie is fail-open: voeg indien nodig uw eigen filtering toe