Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

HTTP-fouten en beveiliging van API-sleutels

Les 13 van 14 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Fouten afhandelen en uw inloggegevens beschermen
  2. HTTP-foutcodes
  3. Stel de API-sleutel nooit bloot aan de client
  4. Fail-open moderatie
  5. Belangrijkste punten

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