Przejdź do głównej treści
Polski— Wybierz język
Menu

Błędy HTTP i bezpieczeństwo klucza API

Lekcja 13 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Obsługa błędów i ochrona poświadczeń
  2. Kody błędów HTTP
  3. Nigdy nie udostępniaj klucza API po stronie klienta
  4. Moderacja typu fail-open
  5. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie stron xAI Text to Speech oraz Rate limits: tekst ograniczony do 60 000 znaków, błąd 404 (nieznany głos) oraz limity szybkości w zależności od poziomu. Źródła: Text to Speech · Rate limits.

Obsługa błędów i ochrona poświadczeń

W środowisku produkcyjnym Twoja aplikacja musi poprawnie obsługiwać błędy API TTS i przede wszystkim nigdy nie udostępniać klucza API po stronie klienta. Ta lekcja omawia kody błędów, strategie ponawiania prób oraz architekturę proxy backendowego.

Kody błędów HTTP

API TTS zwraca standardowe kody błędów HTTP. Oto jak reagować na każdy z nich.

400: Bad Request (Błędne żądanie)

Serwer nie mógł przetworzyć Twojego żądania. Najczęstsze przyczyny:

  • Pusty tekst lub tekst przekraczający 60 000 znaków
  • Nieprawidłowy kodek (literówka w nazwie)
  • Nieobsługiwana częstotliwość próbkowania
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Nie ponawiaj automatycznie próby przy błędzie 400: problem leży po stronie Twojego żądania, a nie serwera. Najpierw napraw parametry.

401: Unauthorized (Nieautoryzowany)

Klucz API jest nieprawidłowy, wygasł lub brak go:

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

Sprawdź, czy:

  • Nagłówek Authorization jest obecny
  • Format to Bearer xai-... (ze spacją po słowie Bearer)
  • Klucz nie został odwołany w konsoli xAI

404: Not Found (Nie znaleziono)

ID głosu jest nieznane: sprawdź je za pomocą GET /v1/tts/voices dla głosu wbudowanego lub GET /v1/custom-voices dla głosu niestandardowego. Podobnie jak w przypadku 400, błąd 404 nie zniknie po ponowieniu próby.

429: Too Many Requests (Zbyt wiele żądań)

Przekroczyłeś limit szybkości: w warstwie wejściowej wynosi on 50 żądań na sekundę i 100 równoczesnych sesji dla TTS zgodnie ze stroną Rate limits, oraz 50 równoczesnych sesji WebSocket na zespół zgodnie ze stroną Text to Speech. xAI zaleca ponawianie prób z wykładniczym opóźnieniem (exponential backoff):

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

Zaimplementuj wykładnicze opóźnienie dla błędów 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 (Błąd serwera)

Serwer ma tymczasowy problem. Ponów próbę z opóźnieniem:

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

Błędy 503 są często spowodowane chwilowym przeciążeniem. Zazwyczaj ustępują w ciągu kilku sekund.

Nigdy nie udostępniaj klucza API po stronie klienta

To najważniejsza zasada bezpieczeństwa. Jeśli Twój klucz API jest widoczny w JavaScript przeglądarki, każdy może:

  • Wykorzystać Twój limit darmowych zasobów
  • Wygenerować koszty na Twoim koncie
  • Uzyskać dostęp do każdego punktu końcowego API xAI za pomocą Twojego klucza

Architektura proxy backendowego

Rozwiązaniem jest przekazywanie wywołań TTS przez własny backend:

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

Przykład w 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));
});

Przykład w 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 WebSocket

W przypadku WebSocket TTS Twój backend musi przekazywać wiadomości między klientem 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());
});

Moderacja typu fail-open

API TTS uruchamia moderację treści asynchronicznie. Oznacza to, że moderacja nie blokuje żądania: audio jest generowane i zwracane, nawet jeśli moderacja nie zakończyła jeszcze swojej analizy.

Jeśli treść zostanie oznaczona jako niewłaściwa, raport pojawi się post factum. Dlatego Twoja aplikacja powinna w razie potrzeby uruchomić własną moderację wcześniej (upstream).

Kluczowe wnioski

  • 400 = błąd parametru (nie ponawiaj; napraw żądanie)
  • 401 = nieprawidłowy klucz API (sprawdź nagłówek Authorization)
  • 429 = ograniczenie szybkości (wykładnicze opóźnienie)
  • 500/503 = tymczasowy błąd serwera (ponów z opóźnieniem)
  • Nigdy nie udostępniaj klucza API w kodzie klienta
  • Przekazuj wszystkie wywołania TTS przez swój backend
  • Moderacja działa w trybie fail-open: dodaj własne filtrowanie, jeśli jest potrzebne