Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Erros HTTP e segurança da chave de API

Aula 13 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Tratar erros e proteger as suas credenciais
  2. Códigos de erro HTTP
  3. Nunca exponha a chave de API no cliente
  4. Moderação fail-open
  5. Pontos-chave

Atualizado a 3 de novembro de 2026, com base nas páginas Text to Speech e Rate limits da xAI: texto limitado a 60.000 carateres, o erro 404 (voz desconhecida) e limites de taxa por nível. Fontes: Text to Speech · Rate limits.

Tratar erros e proteger as suas credenciais

Em produção, a sua aplicação tem de tratar os erros da API TTS de forma elegante e, acima de tudo, nunca expor a sua chave de API no cliente. Esta lição abrange códigos de erro, estratégias de nova tentativa e a arquitetura de proxy no backend.

Códigos de erro HTTP

A API TTS devolve códigos de erro HTTP padrão. Eis como reagir a cada um.

400: Bad Request

O servidor não conseguiu processar o seu pedido. Causas comuns:

  • Texto vazio ou texto com mais de 60.000 carateres
  • Um codec inválido (um erro de digitação no nome)
  • Uma taxa de amostragem não suportada
if response.status_code == 400:
    error = response.json()
    print(f"Invalid request: {error}")
    # Fix the parameters and try again

Não tente novamente automaticamente um erro 400: o problema está no seu pedido, não no servidor. Corrija primeiro os parâmetros.

401: Unauthorized

A chave de API é inválida, expirou ou está em falta:

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

Verifique se:

  • O cabeçalho Authorization está presente
  • O formato é Bearer xai-... (com um espaço após Bearer)
  • A chave não foi revogada na consola da xAI

404: Not Found

O ID da voz é desconhecido: verifique-o com GET /v1/tts/voices para uma voz integrada, ou GET /v1/custom-voices para uma voz personalizada. Tal como o 400, um 404 não desaparece se tentar novamente.

429: Too Many Requests

Excedeu um limite de taxa: no nível de entrada, 50 pedidos por segundo e 100 sessões simultâneas para TTS, segundo a página Rate limits, e 50 sessões WebSocket simultâneas por equipa, segundo a página Text to Speech. A xAI recomenda tentar novamente com recuo exponencial:

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

Implemente recuo exponencial para erros 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

O servidor tem um problema temporário. Tente novamente com recuo:

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

Os erros 503 são frequentemente causados por sobrecarga temporária. Normalmente resolvem-se em poucos segundos.

Nunca exponha a chave de API no cliente

Esta é a regra de segurança mais importante. Se a sua chave de API estiver visível no JavaScript do navegador, qualquer pessoa pode:

  • Utilizar a sua quota gratuitamente
  • Acumular custos na sua conta
  • Aceder a todos os pontos de extremidade da API da xAI com a sua chave

Arquitetura de proxy no backend

A solução é fazer proxy das chamadas TTS através do seu próprio backend:

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

Exemplo em 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));
});

Exemplo em 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"]
    )

Proxy WebSocket

Para o WebSocket TTS, o seu backend tem de retransmitir mensagens entre o cliente e a API da 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());
});

Moderação fail-open

A API TTS executa a moderação de conteúdo de forma assíncrona. Isso significa que a moderação não bloqueia o pedido: o áudio é gerado e devolvido mesmo que a moderação não tenha terminado a sua análise.

Se o conteúdo for assinalado como inadequado, o relatório chega depois do facto. Por isso, a sua aplicação deve executar a sua própria moderação a montante, se necessário.

Pontos-chave

  • 400 = erro de parâmetro (não tente novamente; corrija o pedido)
  • 401 = chave de API inválida (verifique o cabeçalho Authorization)
  • 429 = limite de taxa excedido (recuo exponencial)
  • 500/503 = erro temporário do servidor (tente novamente com recuo)
  • Nunca exponha a chave de API no código do cliente
  • Faça proxy de todas as chamadas TTS através do seu backend
  • A moderação é fail-open: adicione o seu próprio filtro se necessário