Премини към основното съдържание
Български— Изберете език
Меню

Грешки в HTTP и сигурност на API ключа

Урок 13 от 14 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Обработка на грешки и защита на идентификационните данни
  2. HTTP кодове за грешки
  3. Никога не излагайте API ключа на клиентската страна
  4. Модерация с принцип „fail-open“
  5. Ключови изводи

Обновено на 3 ноември 2026 г., въз основа на страниците Text to Speech и Rate limits на xAI: текстът е ограничен до 60 000 знака, грешка 404 (непознат глас) и лимити на заявките според нивото. Източници: Text to Speech · Rate limits.

Обработка на грешки и защита на идентификационните данни

В производствена среда Вашето приложение трябва да обработва грешките на TTS API по елегантен начин и преди всичко никога да не излага API ключа Ви на клиентската страна. Този урок обхваща кодове за грешки, стратегии за повторни опити и архитектурата на бекенд прокси.

HTTP кодове за грешки

TTS API връща стандартни HTTP кодове за грешки. Ето как да реагирате на всеки от тях.

400: Bad Request (Невалидна заявка)

Сървърът не може да обработи Вашата заявка. Чести причини:

  • Празен текст или текст над 60 000 знака
  • Невалиден кодек (правописна грешка в името)
  • Неподдържана честота на дискретизация (sample rate)
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Не правете автоматичен повторен опит при грешка 400: проблемът е във Вашата заявка, а не в сървъра. Първо коригирайте параметрите.

401: Unauthorized (Неоторизиран достъп)

API ключът е невалиден, изтекъл или липсва:

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

Проверете дали:

  • Заглавката Authorization присъства
  • Форматът е Bearer xai-... (с интервал след Bearer)
  • Ключът не е бил отменен в конзолата на xAI

404: Not Found (Не е намерено)

ID на гласа е непознат: проверете го чрез GET /v1/tts/voices за вграден глас или GET /v1/custom-voices за персонализиран глас. Както при 400, грешка 404 няма да изчезне, ако направите повторен опит.

429: Too Many Requests (Твърде много заявки)

Надхвърлили сте лимит на заявките: за входното ниво – 50 заявки в секунда и 100 едновременни сесии за TTS според страницата Rate limits, и 50 едновременни WebSocket сесии на екип според страницата Text to Speech. xAI препоръчва повторен опит с експоненциално забавяне (exponential backoff):

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

Приложете експоненциално забавяне за грешки 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 (Грешка в сървъра)

Сървърът има временен проблем. Направете повторен опит със забавяне:

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

Грешките 503 често са причинени от временно претоварване. Обикновено се изчистват в рамките на няколко секунди.

Никога не излагайте API ключа на клиентската страна

Това е най-важното правило за сигурност. Ако Вашият API ключ е видим в JavaScript на браузъра, всеки може да:

  • Използва Вашата квота безплатно
  • Натрупа такси във Вашия акаунт
  • Достъпи всеки крайна точка на xAI API с Вашия ключ

Архитектура на бекенд прокси

Решението е да проксирате TTS повикванията чрез Вашия собствен бекенд:

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

Пример с 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));
});

Пример с 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"]
    )

WebSocket прокси

За TTS WebSocket Вашият бекенд трябва да препраща съобщения между клиента и xAI API:

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

Модерация с принцип „fail-open“

TTS API изпълнява модерация на съдържанието асинхронно. Това означава, че модерацията не блокира заявката: аудиото се генерира и връща, дори ако модерацията все още не е приключила анализа си.

Ако съдържанието бъде маркирано като неподходящо, докладът идва постфактум. Затова Вашето приложение трябва да изпълнява собствена модерация предварително, ако е необходимо.

Ключови изводи

  • 400 = грешка в параметър (не правете повторен опит; поправете заявката)
  • 401 = невалиден API ключ (проверете заглавката Authorization)
  • 429 = ограничен брой заявки (експоненциално забавяне)
  • 500/503 = временна грешка в сървъра (повторен опит със забавяне)
  • Никога не излагайте API ключа в клиентския код
  • Проксирайте всички TTS повиквания чрез Вашия бекенд
  • Модерацията работи на принципа „fail-open“: добавете собствен филтър, ако е необходимо