Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

HTTP-virheet ja API-avaimen suojaus

Oppitunti 13 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Virheiden käsittely ja tunnistetietojen suojaaminen
  2. HTTP-virhekoodit
  3. Älä koskaan paljasta API-avainta asiakaspuolella
  4. Fail-open-moderointi
  5. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n Text to Speech - ja Rate limits -sivujen perusteella: teksti rajoitettu 60 000 merkkiin, 404-virhe (tuntematon ääni) ja käyttörajat tason mukaan. Lähteet: Text to Speech · Rate limits.

Virheiden käsittely ja tunnistetietojen suojaaminen

Tuotantoympäristössä sovelluksesi tulee käsitellä TTS-API:n virheet hallitusti, eikä ennen kaikkea saa koskaan paljastaa API-avainta asiakaspuolella. Tämä oppitunti käsittelee virhekoodeja, uudelleenyrittämisstrategioita ja backend-välityspalvelinarkkitehtuuria.

HTTP-virhekoodit

TTS-API palauttaa standardit HTTP-virhekoodit. Tässä ohjeet siihen, miten kuhunkin koodiin tulee reagoida.

400: Bad Request (Virheellinen pyyntö)

Palvelin ei pystynyt käsittelemään pyyntöäsi. Yleisimmät syyt:

  • Tyhjä teksti tai teksti, joka ylittää 60 000 merkkiä
  • Virheellinen koodekki (nimessä oleva kirjoitusvirhe)
  • Ei-tuettu näytteenottotaajuus
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Älä yritä automaattisesti uudelleen 400-virheen jälkeen: ongelma on pyynnössäsi, ei palvelimella. Korjaa parametrit ensin.

401: Unauthorized (Valtuuttamaton)

API-avain on virheellinen, vanhentunut tai puuttuu:

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

Tarkista, että:

  • Authorization-otsake on läsnä
  • Muoto on Bearer xai-... (välilyönti sanan Bearer jälkeen)
  • Avainta ei ole mitätöity xAI-konsolissa

404: Not Found (Ei löytynyt)

Äänen ID on tuntematon: tarkista se komennolla GET /v1/tts/voices sisäänrakennetun äänen osalta tai GET /v1/custom-voices mukautetun äänen osalta. Kuten 400-virheen kohdalla, 404-virhe ei poistu uudelleenyrittämisellä.

429: Too Many Requests (Liian monta pyyntöä)

Olet ylittänyt käyttörajan: aloitustasolla raja on 50 pyyntöä sekunnissa ja 100 samanaikaista istuntoa TTS:lle Rate limits -sivun mukaan, sekä 50 samanaikaista WebSocket-istuntoa tiimiä kohden Text to Speech -sivun mukaan. xAI suosittelee uudelleenyrittämistä eksponentiaalisella viiveellä (exponential backoff):

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

Toteuta eksponentiaalinen viive 429-virheille:

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 (Palvelinvirhe)

Palvelimella on väliaikainen ongelma. Yritä uudelleen eksponentiaalisella viiveellä:

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

503-virheet johtuvat usein väliaikaisesta ylikuormituksesta. Ne yleensä korjaantuvat muutamassa sekunnissa.

Älä koskaan paljasta API-avainta asiakaspuolella

Tämä on tärkein turvallisuussääntö. Jos API-avaimesi on näkyvissä selaimen JavaScript-koodissa, kuka tahansa voi:

  • Käyttää kiintiösi ilmaiseksi
  • Aiheuttaa kuluja tilillesi
  • Päästä käsiksi kaikkiin xAI-API-päätepisteisiin avaimellasi

Backend-välityspalvelinarkkitehtuuri

Ratkaisu on välittää TTS-pyynnöt oman backendisi kautta:

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

Express.js-esimerkki

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-esimerkki (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-välitys

TTS-WebSocketiä varten backendisi täytyy välittää viestejä asiakkaan ja xAI-API:n välillä:

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-moderointi

TTS-API suorittaa sisältömoderoinnin asynkronisesti. Tämä tarkoittaa, että moderointi ei estä pyyntöä: ääni generoidaan ja palautetaan, vaikka moderointi ei olisi vielä saanut analyysiään valmiiksi.

Jos sisältö merkitään sopimattomaksi, raportti saapuu jälkikäteen. Sovelluksesi tulisi siis tarvittaessa suorittaa oma moderointinsa ennakolta.

Keskeiset asiat

  • 400 = parametrivirhe (älä yritä uudelleen; korjaa pyyntö)
  • 401 = virheellinen API-avain (tarkista Authorization-otsake)
  • 429 = käyttöraja ylitetty (eksponentiaalinen viive)
  • 500/503 = väliaikainen palvelinvirhe (yritä uudelleen viiveellä)
  • Älä koskaan paljasta API-avainta asiakaskoodissa
  • Välitä kaikki TTS-pyynnöt backendisi kautta
  • Moderointi on fail-open: lisää oma suodatuksesi tarvittaessa