Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Earráidí HTTP agus slándáil eochracha API

Ceacht 13 as 14 Nuashonraithe 3 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Earráidí a láimhseáil agus do chreidiúintí a chosaint
  2. Cóid earráide HTTP
  3. Ná nocht an eochair API ar an gcliant riamh
  4. Moderation fail-open
  5. Príomhphointí

Nuashonraithe an 3 Samhain, 2026, bunaithe ar leathanaigh Text to Speech agus Rate limits de chuid xAI: téacs teoranta do 60,000 carachtar, an earráid 404 (guth anaithnid), agus teorainneacha ráta de réir céime. Foincí: Text to Speech · Rate limits.

Earráidí a láimhseáil agus do chreidiúintí a chosaint

Sa táirgeadh, ní mór d’fheidhmchlár earráidí TTS API a láimhseáil go réidh agus, os cionn gach rud, do eochair API a nochtadh ar an gcliant faoi sem aon uair. Clúdaíonn an ceacht seo cóid earráide, straitéisí athiarrtha, agus ailtireacht seachfhreastalaí (backend proxy).

Cóid earráide HTTP

Tugann an TTS API cóid earráide HTTP caighdeánacha ar ais. Seo conas freagairt do gach ceann acu.

400: Bad Request

Níorbh fhéidir leis an bhfreastalaí d’iarratas a phróiseáil. Cúiseanna coitianta:

  • Téacs folamh nó téacs thar 60,000 carachtar
  • Cóidec neamhbhailí (botún cló sa ainm)
  • Ráta samplála nach dtacaítear leis
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Ná déan iarracht arís go huathoibríoch ar earráid 400: is i d’iarratas atá an fhadhb, ní ar an bhfreastalaí. Deisigh na paraiméadair ar dtús.

401: Unauthorized

Tá an eochair API neamhbhailí, imithe in éag, nó ar iarraidh:

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

Seiceáil go bhfuil:

  • An ceanntásc Authorization i láthair
  • An formáid Bearer xai-... (le spás tar éis Bearer)
  • Nár cúlghaireadh an eochair sa chonsól xAI

404: Not Found

Tá ID an ghutha anaithnid: seiceáil é le GET /v1/tts/voices do ghuth ionsuite, nó GET /v1/custom-voices do ghuth saincheaptha. Cosúil le 400, ní rachaidh 404 ar ceal má dhéanann tú iarracht arís.

429: Too Many Requests

Tá tú tar éis teorainn ráta a shárú: ar an gcéad iontrála, 50 iarratas in aghaidh an tsoicind agus 100 seisiún comhthreomhar do TTS de réir an leathanaigh Rate limits, agus 50 seisiún WebSocket comhthreomhar in aghaidh an fhoirne de réir an leathanaigh Text to Speech. Molann xAI iarracht arís le cúlú easpónantúil (exponential backoff):

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

Cuir cúlú easpónantúil i bhfeidhm d’earráidí 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

Tá fadhb shealadach ag an bhfreastalaí. Déan iarracht arís le cúlú:

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

Is minic a bhíonn earráidí 503 mar gheall ar ualach sealadach. De ghnáth, réitíonn siad laistigh de chúpla soicind.

Ná nocht an eochair API ar an gcliant riamh

Seo an riail slándála is tábhachtaí. Má tá d’eochair API le feiceáil i JavaScript an bhrabhsálaí, is féidir le duine ar bith:

  • Do chuóta a úsáid saor in aisce
  • Muirir a charnadh ar do chuntas
  • Gach críochphointe API xAI a rochtain le d’eochair

Ailtireacht seachfhreastalaí (Backend proxy)

Is é an réiteach ná glaonna TTS a sheachfhreastalú trí do bhonnseirbhís féin:

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

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

Sampla 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"]
    )

Seachfhreastalaí WebSocket

Do WebSocket TTS, caithfidh do bhonnseirbhís teachtaireachtaí a athsheoladh idir an cliant agus API 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());
});

Moderation fail-open

Ritheann an TTS API modhnú ábhair go hasionchrónach. Ciallaíonn sé sin nach gcuireann an modhnú bac ar an iarratas: gintear an fuaime agus filltear í fiú mura bhfuil anailís an mhodhnaithe críochnaithe.

Má chuirtear ábhar faoi bhratach mar ábhar míchuí, tagann an tuarascáil tar éis na himeachta. Mar sin, ba chóir d’fheidhmchlár a mhodhnú féin a rith suas srutha más gá.

Príomhphointí

  • 400 = earráid paraiméadair (ná déan iarracht arís; deisigh an t-iarratas)
  • 401 = eochair API neamhbhailí (seiceáil an ceanntásc Authorization)
  • 429 = teorainn ráta sáraithe (cúlú easpónantúil)
  • 500/503 = earráid freastalaí shealadach (déan iarracht arís le cúlú)
  • Ná nocht an eochair API i gcód clianta riamh
  • Seachfhreastalaigh gach glao TTS trí do bhonnseirbhís
  • Is modhnú fail-open é: cuir do scagadh féin leis más gá