Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Chyby HTTP a bezpečnosť API kľúčov

Lekcia 13 z 14 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Spracovanie chýb a ochrana poverení
  2. Chybové kódy HTTP
  3. Nikdy neodhaľuj API kľúč na strane klienta
  4. Moderácia s princípom „fail-open“
  5. Kľúčové poznatky

Aktualizované 3. novembra 2026 na základe stránok xAI Text to Speech a Rate limits: text obmedzený na 60 000 znakov, chyba 404 (neznámy hlas) a limity rýchlosti podľa úrovne. Zdroje: Text to Speech · Rate limits.

Spracovanie chýb a ochrana poverení

V produkčnom prostredí musí tvoja aplikácia elegantne spracovávať chyby TTS API a predovšetkým nikdy neodhaľovať tvoj API kľúč na strane klienta. Táto lekcia pokrýva chybové kódy, stratégie opakovania a architektúru backendového proxy.

Chybové kódy HTTP

TTS API vracia štandardné chybové kódy HTTP. Tu je návod, ako reagovať na každý z nich.

400: Bad Request (Neplatná požiadavka)

Server nedokázal spracovať tvoju požiadavku. Bežné príčiny:

  • Prázdny text alebo text dlhší ako 60 000 znakov
  • Neplatný kodek (preklep v názve)
  • Nepodporovaná vzorkovacia frekvencia
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Neopakuj chybu 400 automaticky: problém je v tvojej požiadavke, nie na serveri. Najprv oprav parametre.

401: Unauthorized (Neoprávnený prístup)

API kľúč je neplatný, vypršal alebo chýba:

if response.status_code == 401:
    raise AuthenticationError("Invalid or expired API key")

Skontroluj, či:

  • Je prítomná hlavička Authorization
  • Formát je Bearer xai-... (s medzerou za slovom Bearer)
  • Kľúč nebol zrušený v konzole xAI

404: Not Found (Nenájdené)

ID hlasu je neznáme: over si ho pomocou GET /v1/tts/voices pre vstavaný hlas alebo GET /v1/custom-voices pre vlastný hlas. Podobne ako pri chybe 400, ani chyba 404 nezmizne, ak požiadavku zopakuješ.

429: Too Many Requests (Príliš veľa požiadaviek)

Prekročil si limit rýchlosti: na vstupnej úrovni je to 50 požiadaviek za sekundu a 100 súbežných relácií pre TTS podľa stránky Rate limits a 50 súbežných WebSocket relácií na tím podľa stránky Text to Speech. xAI odporúča opakovať pokus s exponenciálnym oneskorením (exponential backoff):

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

Implementuj exponenciálne oneskorenie pre chyby 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"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 (Chyba servera)

Server má dočasný problém. Opakuj pokus s oneskorením:

if response.status_code in (500, 503):
    # Retry with exponential backoff
    pass

Chyby 503 sú často spôsobené dočasným preťažením. Zvyčajne sa vyriešia v priebehu niekoľkých sekúnd.

Nikdy neodhaľuj API kľúč na strane klienta

Toto je najdôležitejšie bezpečnostné pravidlo. Ak je tvoj API kľúč viditeľný v JavaScripte prehliadača, ktokoľvek môže:

  • Využívať tvoju kvótu zadarmo
  • Navýšiť poplatky na tvojom účte
  • Pristupovať ku každému koncovému bodu API xAI s tvojím kľúčom

Architektúra backendového proxy

Riešením je smerovať volania TTS cez tvoj vlastný backend:

Browser -> Your backend -> xAI API
 (no key)    (API key)      (TTS)

Príklad v 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));
});

Príklad vo 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"]
    )

Proxy pre WebSocket

Pre TTS WebSocket musí tvoj backend prepájať správy medzi klientom a API 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}` } }
  );

  // 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());
});

Moderácia s princípom „fail-open“

API TTS vykonáva moderáciu obsahu asynchrónne. To znamená, že moderácia neblokuje požiadavku: audio sa vygeneruje a vráti, aj keď moderácia ešte nedokončila analýzu.

Ak je obsah označený ako nevhodný, správa príde dodatočne. Tvoja aplikácia by preto mala v prípade potreby spustiť vlastnú moderáciu vopred (upstream).

Kľúčové poznatky

  • 400 = chyba parametra (neopakuj; oprav požiadavku)
  • 401 = neplatný API kľúč (skontroluj hlavičku Authorization)
  • 429 = obmedzená rýchlosť (exponenciálne oneskorenie)
  • 500/503 = dočasná chyba servera (opakuj s oneskorením)
  • Nikdy neodhaľuj API kľúč v kóde na strane klienta
  • Smeruj všetky volania TTS cez tvoj backend
  • Moderácia funguje na princípe „fail-open“: v prípade potreby pridaj vlastné filtrovanie