Erori HTTP și securitatea cheii API
Pe această pagină
Actualizat la 3 noiembrie 2026, pe baza paginilor xAI Text to Speech și Rate limits: text limitat la 60.000 de caractere, eroarea 404 (voce necunoscută) și limitele de rată pe niveluri. Surse: Text to Speech · Rate limits.
Gestionarea erorilor și protejarea credențialelor
În producție, aplicația dumneavoastră trebuie să gestioneze erorile API-ului TTS cu grație și, mai presus de toate, să nu expună niciodată cheia API pe partea de client (client-side). Această lecție acoperă codurile de eroare, strategiile de reîncercare și arhitectura de proxy backend.
Coduri de eroare HTTP
API-ul TTS returnează coduri de eroare HTTP standard. Iată cum să reacționați la fiecare dintre ele.
400: Bad Request (Cerere incorectă)
Serverul nu a putut procesa cererea dumneavoastră. Cauze frecvente:
- Text gol sau text care depășește 60.000 de caractere
- Un codec invalid (o greșeală de tastare în nume)
- O frecvență de eșantionare (sample rate) neacceptată
if response.status_code == 400:
error = response.json()
print(f"Invalid request: {error}")
# Fix the parameters and try again
Nu reîncercați automat o eroare 400: problema se află în cererea dumneavoastră, nu pe server. Remediați mai întâi parametrii.
401: Unauthorized (Neautorizat)
Cheia API este invalidă, expirată sau lipsește:
if response.status_code == 401:
raise AuthenticationError("Invalid or expired API key")
Verificați dacă:
- Antetul
Authorizationeste prezent - Formatul este
Bearer xai-...(cu un spațiu după Bearer) - Cheia nu a fost revocată în consola xAI
404: Not Found (Negăsit)
ID-ul vocii este necunoscut: verificați-l cu GET /v1/tts/voices pentru o voce integrată sau GET /v1/custom-voices pentru o voce personalizată. La fel ca în cazul unei erori 400, o eroare 404 nu va dispărea dacă reîncercați.
429: Too Many Requests (Prea multe cereri)
Ați depășit o limită de rată: la nivelul de intrare, 50 de cereri pe secundă și 100 de sesiuni concurente pentru TTS conform paginii Rate limits, și 50 de sesiuni WebSocket concurente per echipă conform paginii Text to Speech. xAI recomandă reîncercarea cu o strategie de „exponential backoff“ (așteptare exponențială):
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 5))
await asyncio.sleep(retry_after)
# Try again
Implementați exponential backoff pentru erorile 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 (Eroare de server)
Serverul întâmpină o problemă temporară. Reîncercați cu backoff:
if response.status_code in (500, 503):
# Retry with exponential backoff
pass
Erorile 503 sunt cauzate adesea de o supraîncărcare temporară. Acestea se rezolvă de obicei în câteva secunde.
Nu expuneți niciodată cheia API pe client
Aceasta este cea mai importantă regulă de securitate. Dacă cheia dumneavoastră API este vizibilă în JavaScript-ul browserului, oricine poate:
- Să utilizeze cota dumneavoastră gratuit
- Să genereze costuri în contul dumneavoastră
- Să acceseze fiecare endpoint API xAI cu cheia dumneavoastră
Arhitectura de proxy backend
Soluția este să proxy-ați apelurile TTS prin propriul dumneavoastră backend:
Browser -> Your backend -> xAI API
(no key) (API key) (TTS)
Exemplu 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));
});
Exemplu 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
Pentru WebSocket TTS, backend-ul dumneavoastră trebuie să retransmită mesajele între client și API-ul 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());
});
Moderare de tip „fail-open“
API-ul TTS rulează moderarea conținutului asincron. Aceasta înseamnă că moderarea nu blochează cererea: audio-ul este generat și returnat chiar dacă moderarea nu și-a finalizat analiza.
Dacă conținutul este marcat ca inadecvat, raportul vine după fapt. Prin urmare, aplicația dumneavoastră ar trebui să ruleze propria moderare în amonte, dacă este necesar.
Puncte cheie
- 400 = eroare de parametru (nu reîncercați; remediați cererea)
- 401 = cheie API invalidă (verificați antetul Authorization)
- 429 = limită de rată atinsă (exponential backoff)
- 500/503 = eroare temporară de server (reîncercați cu backoff)
- Nu expuneți niciodată cheia API în codul de client
- Proxy-ați toate apelurile TTS prin backend-ul dumneavoastră
- Moderarea este de tip „fail-open“: adăugați propriul filtraj dacă este necesar