Σφάλματα HTTP και ασφάλεια κλειδιού API
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 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: προσθέστε το δικό σας φίλτρο αν χρειάζεται