Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

HTTP pogreške i sigurnost API ključa

Lekcija 13 od 14 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Rukovanje pogreškama i zaštita vjerodajnica
  2. HTTP kodovi pogrešaka
  3. Nikada ne izlaži API ključ na klijentu
  4. Moderacija tipa „fail-open“
  5. Ključne točke

Ažurirano 3. studenog 2026., na temelju stranica xAI Text to Speech i Rate limits: tekst ograničen na 60.000 znakova, pogreška 404 (nepoznat glas) i ograničenja stope po razini. Izvori: Text to Speech · Rate limits.

Rukovanje pogreškama i zaštita vjerodajnica

U proizvodnji tvoja aplikacija mora pravilno obrađivati pogreške TTS API-ja i, prije svega, nikada ne smije izložiti tvoj API ključ na klijentskoj strani. Ova lekcija pokriva kodove pogrešaka, strategije ponovnih pokušaja i arhitekturu poslužiteljskog proxyja.

HTTP kodovi pogrešaka

TTS API vraća standardne HTTP kodove pogrešaka. Evo kako reagirati na svaki od njih.

400: Bad Request (Neispravan zahtjev)

Poslužitelj nije mogao obraditi tvoj zahtjev. Uobičajeni uzroci:

  • Prazan tekst ili tekst dulji od 60.000 znakova
  • Neispravan kodek (tipfeler u nazivu)
  • Nepodržana frekvencija uzorkovanja
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Nemoj automatski ponavljati pogrešku 400: problem je u tvom zahtjevu, a ne na poslužitelju. Prvo ispravi parametre.

401: Unauthorized (Neovlašteno)

API ključ je neispravan, istekao ili nedostaje:

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

Provjeri sljedeće:

  • Zaglavlje Authorization je prisutno
  • Format je Bearer xai-... (s razmakom nakon Bearer)
  • Ključ nije opozvan u xAI konzoli

404: Not Found (Nije pronađeno)

ID glasa je nepoznat: provjeri ga s GET /v1/tts/voices za ugrađeni glas ili GET /v1/custom-voices za prilagođeni glas. Kao i kod 400, pogreška 404 neće nestati ako pokušaš ponovno.

429: Too Many Requests (Previše zahtjeva)

Premašio/la si ograničenje stope: na ulaznoj razini, 50 zahtjeva u sekundi i 100 istovremenih sesija za TTS prema stranici Rate limits, te 50 istovremenih WebSocket sesija po timu prema stranici Text to Speech. xAI preporučuje ponovni pokušaj s eksponencijalnim kašnjenjem (exponential backoff):

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

Implementiraj eksponencijalno kašnjenje za pogreške 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 (Pogreška poslužitelja)

Poslužitelj ima privremeni problem. Pokušaj ponovno s eksponencijalnim kašnjenjem:

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

Pogreške 503 često su uzrokovane privremenim preopterećenjem. Obično se riješe unutar nekoliko sekundi.

Nikada ne izlaži API ključ na klijentu

Ovo je najvažnije sigurnosno pravilo. Ako je tvoj API ključ vidljiv u JavaScriptu preglednika, bilo tko može:

  • Besplatno koristiti tvoju kvotu
  • Napraviti troškove na tvom računu
  • Pristupiti svakoj xAI API endpoint točki s tvojim ključem

Arhitektura poslužiteljskog proxyja

Rješenje je proksimirati TTS pozive kroz vlastiti backend:

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

Primjer s 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));
});

Primjer s FastAPI-jem (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

Za TTS WebSocket, tvoj backend mora proslijeđivati poruke između klijenta i xAI API-ja:

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

Moderacija tipa „fail-open“

TTS API pokreće moderaciju sadržaja asinkrono. To znači da moderacija ne blokira zahtjev: audio se generira i vraća čak i ako moderacija nije završila svoju analizu.

Ako se sadržaj označi kao neprikladan, izvještaj stiže naknadno. Stoga bi tvoja aplikacija trebala pokrenuti vlastitu moderaciju unaprijed ako je potrebno.

Ključne točke

  • 400 = pogreška parametra (nemoj ponavljati; ispravi zahtjev)
  • 401 = neispravan API ključ (provjeri zaglavlje Authorization)
  • 429 = ograničena stopa (eksponencijalno kašnjenje)
  • 500/503 = privremena pogreška poslužitelja (ponovi s kašnjenjem)
  • Nikada ne izlaži API ključ u klijentskom kodu
  • Proksimiraj sve TTS pozive kroz svoj backend
  • Moderacija je tipa „fail-open“: dodaj vlastito filtriranje ako je potrebno