Błędy HTTP i bezpieczeństwo klucza API
Na tej stronie
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
Authorizationjest 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