xAI realtime client secret request failed: ${response.status

Error message

xAI realtime client secret request failed: ${response.status} ${text}

What it means

XaiRealtimeModel.doCreateClientSecret POSTs to {baseURL}/realtime/client_secrets to mint an ephemeral client secret for realtime WebSocket sessions. When the HTTP response is not ok, the raw status and response body are wrapped in a plain Error. This is an API-level failure: auth, wrong model, quota, or endpoint availability.

Source

Thrown at packages/xai/src/realtime/xai-realtime-model.ts:58

    const url = `${this.config.baseURL}/realtime/client_secrets`;

    const body: Record<string, unknown> = {};
    if (options.expiresAfterSeconds != null) {
      body.expires_after = { seconds: options.expiresAfterSeconds };
    }

    const response = await fetchFn(url, {
      method: 'POST',
      headers: {
        ...this.config.headers(),
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    });

    if (!response.ok) {
      const text = await response.text();
      throw new Error(
        `xAI realtime client secret request failed: ${response.status} ${text}`,
      );
    }

    const data = (await response.json()) as {
      value: string;
      expires_at?: number;
    };

    return {
      token: data.value,
      // xAI selects the voice model from the `model` query parameter on the
      // WebSocket URL. Without it the model choice is silently ignored and the
      // server falls back to its default voice model.
      url: `wss://${new URL(this.config.baseURL).host}/v1/realtime?model=${encodeURIComponent(this.modelId)}`,
      expiresAt: data.expires_at,
    };
  }

View on GitHub (pinned to 69428b1f8b)

Solutions

Check the status/body in the message: fix 401 by setting a valid XAI_API_KEY, fix 404 by confirming the model supports realtime and the account has access
Verify baseURL is correct (default https://api.x.ai/v1) and reachable from your network
Retry on 429/5xx with backoff; if persistent, check xAI status or support

Example fix

// before
const secret = await model.doCreateClientSecret({});
// after
try {
  const secret = await model.doCreateClientSecret({});
} catch (e) {
  console.error('client secret failed:', (e as Error).message); // inspect status/text
}

Defensive patterns

Strategy: retry

Validate before calling

if (!process.env.XAI_API_KEY) throw new Error('XAI_API_KEY missing before requesting realtime client secret');

Type guard

null

Try / catch

try {
  const secret = await model.doCreateClientSecret({ expiresAfterSeconds: 3600 });
} catch (e) {
  const msg = (e as Error).message;
  if (msg.includes(' 401 ') || msg.includes(' 403 ')) {
    // fix credentials
  } else if (/ 429 | 5\d\d /.test(msg)) {
    // retry with backoff
  }
}

Prevention

Verify XAI_API_KEY validity and realtime model access before deploying
Use the default baseURL unless deliberately pointing at a gateway
Apply exponential backoff for 429/5xx responses

When it happens

Trigger: Calling createClientSecret on an xai realtime model when the xAI API returns 401 (invalid API key), 403, 404 (realtime endpoint not enabled for the account/model), or 429/5xx responses.

Common situations: Missing or revoked XAI_API_KEY; using a model id without realtime access; corporate proxy returning non-2xx; base URL misconfigured to a non-xAI gateway.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/763931d21fc052f9. Report an issue: GitHub.