Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Σφάλματα HTTP και ασφάλεια κλειδιού API

Μάθημα 13 / 14 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Διαχείριση σφαλμάτων και προστασία των διαπιστευτηρίων σας
  2. Κωδικοί σφάλματος HTTP
  3. Ποτέ μην εκθέτετε το κλειδί API στον πελάτη
  4. Fail-open moderation
  5. Βασικά σημεία

Ενημερώθηκε στις 3 Νοεμβρίου 2026, με βάση τις σελίδες Text to Speech και Rate limits της xAI: όριο κειμένου 60.000 χαρακτήρων, σφάλμα 404 (άγνωστη φωνή) και όρια αιτημάτων ανά επίπεδο. Πηγές: Text to Speech · Rate limits.

Διαχείριση σφαλμάτων και προστασία των διαπιστευτηρίων σας

Σε περιβάλλον παραγωγής, η εφαρμογή σας πρέπει να διαχειρίζεται σωστά τα σφάλματα του TTS API και, πάνω απ’ όλα, να μην εκθέτει ποτέ το κλειδί API σας στον πελάτη (client). Αυτό το μάθημα καλύπτει κωδικούς σφαλμάτων, στρατηγικές επανάληψης και την αρχιτεκτονική διακομιστή μεσολάβησης (backend proxy).

Κωδικοί σφάλματος 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

Το αναγνωριστικό φωνής (voice ID) είναι άγνωστο: ελέγξτε το με GET /v1/tts/voices για ενσωματωμένη φωνή ή GET /v1/custom-voices για προσαρμοσμένη φωνή. Όπως και το 400, το 404 δεν θα διορθωθεί αν κάνετε επανάληψη.

429: Too Many Requests

Έχετε ξεπεράσει ένα όριο αιτημάτων: στο βασικό επίπεδο (entry tier), 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: Σφάλμα Διακομιστή

Ο διακομιστής αντιμετωπίζει ένα προσωρινό πρόβλημα. Κάντε επανάληψη με εκθετική καθυστέρηση:

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

Τα σφάλματα 503 προκαλούνται συχνά από προσωρινή υπερφόρτωση. Συνήθως επιλύονται μέσα σε λίγα δευτερόλεπτα.

Ποτέ μην εκθέτετε το κλειδί API στον πελάτη

Αυτός είναι ο πιο σημαντικός κανόνας ασφαλείας. Αν το κλειδί API σας είναι ορατό στη JavaScript του προγράμματος περιήγησης, οποιοσδήποτε μπορεί να:

  • Χρησιμοποιήσει το όριο χρήσης (quota) σας δωρεάν
  • Σωρεύσει χρεώσεις στον λογαριασμό σας
  • Πρόσβαση σε κάθε τελικό σημείο (endpoint) της xAI API με το κλειδί σας

Αρχιτεκτονική διακομιστή μεσολάβησης (Backend proxy)

Η λύση είναι να διαμεσολαβείτε τις κλήσεις TTS μέσω του δικού σας backend:

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, το backend σας πρέπει να αναμεταδίδει μηνύματα μεταξύ του πελάτη και του 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 moderation

Το TTS API εκτελεί τον έλεγχο περιεχομένου (moderation) ασύγχρονα. Αυτό σημαίνει ότι ο έλεγχος δεν μπλοκάρει το αίτημα: το αρχείο ήχου παράγεται και επιστρέφεται ακόμη και αν ο έλεγχος δεν έχει ολοκληρώσει την ανάλυσή του.

Εάν το περιεχόμενο επισημανθεί ως ακατάλληλο, η αναφορά έρχεται εκ των υστέρων. Επομένως, η εφαρμογή σας θα πρέπει να εκτελεί τον δικό της έλεγχο περιεχομένου εκ των προτέρων, εάν χρειάζεται.

Βασικά σημεία

  • 400 = σφάλμα παραμέτρου (μην κάνετε επανάληψη· διορθώστε το αίτημα)
  • 401 = μη έγκυρο κλειδί API (ελέγξτε την κεφαλίδα Authorization)
  • 429 = όριο αιτημάτων (εκθετική καθυστέρηση)
  • 500/503 = προσωρινό σφάλμα διακομιστή (επανάληψη με καθυστέρηση)
  • Ποτέ μην εκθέτετε το κλειδί API στον κώδικα του πελάτη
  • Διαμεσολαβείτε όλες τις κλήσεις TTS μέσω του backend σας
  • Ο έλεγχος περιεχομένου είναι fail-open: προσθέστε το δικό σας φίλτρο αν χρειάζεται