Python 88.3%
TypeScript 7.6%
Shell 4.1%
1# xAI authentication, base URLs, headers and errors23**Status:** `DOCUMENTED` + `LIVE_VERIFIED` (auth paths, 400/401/404/405/422 shapes, rate-limit headers and regional hosts probed on 2026-09-19; 403/429/5xx not triggered). 4**Sources:** https://docs.x.ai/developers/quickstart · /developers/debugging · /developers/rate-limits · /developers/advanced-api-usage/{regions,mtls,websocket-mode,deferred-chat-completions,prompt-caching/maximizing-cache-hits} · /developers/faq/security · /developers/management-api-guide · /developers/grpc-api-reference · `tmp-live/xai-models/catalogue-probe*.json`. 5**Last verified:** 2026-09-18 · Machine-readable: `generated/fragments/headers/xai-headers.json`, `generated/fragments/errors/xai-errors.json`.67## 1. Authentication89| Credential | Where | Notes |10|---|---|---|11| API key `xai-…` | `Authorization: Bearer <XAI_API_KEY>` on every REST, WebSocket and gRPC call (gRPC: same header as call metadata) | created per team in the console (API Keys) or via the Management API; scoped by ACLs (`api-key:endpoint:*`, `api-key:model:*`); may carry per-key `qps`/`qpm`/`tpm` caps and `expireTime`; can be disabled/blocked; team can be blocked |12| Management key | `Authorization: Bearer <management key>` on `https://management-api.x.ai` | distinct key type; inference key → 401 `{code:16}` |13| OAuth token | `GET /v1/me` documents "works with both API keys and OAuth tokens" (`oauth{client_id}` branch) | OAuth flow itself is not documented publicly |14| mTLS | enterprise, team-level, host `https://mtls.api.x.ai` | client certificate **in addition to** the API key; rotation without downtime; `curl -v https://mtls.api.x.ai/v1/api-key` as smoke test |15| Ephemeral client secrets | `POST /v1/realtime/client_secrets` | short-lived tokens for browser voice clients (voice agent's page) |1617There is **no version header and no beta header**. Introspect a key with `GET /v1/api-key` (acls, blocked/disabled flags) and `GET /v1/me` (user, team, `zdr_status`).1819## 2. Base URLs2021| Host | Scope | Status |22|---|---|---|23| `https://api.x.ai/v1` | global; region not guaranteed | LIVE_VERIFIED |24| `https://us.api.x.ai/v1` | US-only handling, inference, moderation, retained data; **grok-4.6 only**; tokens ×1.1; no image/video/voice; same keys | LIVE_VERIFIED (`GET /v1/models` → only grok-4.6 at 22000/5500/66000 ticks) |25| `https://eu-west-1.api.x.ai/v1` | **undocumented**; `GET /v1/models` → 200 listing only grok-4.3 at global prices (model page lists an `eu-west-1` cluster for grok-4.3 and grok-voice-think-fast-2.0) | LIVE_DISCOVERED — do not rely on for compliance |26| `https://mtls.api.x.ai/v1` | mTLS teams (global only) | DOCUMENTED |27| `wss://api.x.ai/v1/responses` | WebSocket Responses mode | DOCUMENTED |28| `wss://api.x.ai/v1/realtime`, `wss://api.x.ai/v1/stt`, `wss://api.x.ai/v1/tts` | voice | DOCUMENTED |29| `api.x.ai:443` (gRPC) | services `xai_api.*` | DOCUMENTED |30| `https://management-api.x.ai` | Management API | LIVE_VERIFIED (401 with inference key) |31| clusters named in docs | us-east-1, us-west-2, us-central-1, eu-west-1, us-saltlake-2; propagation example `cloud9.api.x.ai`, `us-east-1.api.x.ai` | DOCUMENTED |3233Prompt caches do not carry over between hosts; keep a conversation on one host and set `prompt_cache_key` / `x-grok-conv-id`.3435## 3. Request headers3637| Header | Required | Purpose |38|---|---|---|39| `Authorization: Bearer …` | yes | see §1 |40| `Content-Type: application/json` (multipart for uploads/STT) | for bodies | wrong type → 415 |41| `x-grok-conv-id: <conversation id>` | recommended (Chat Completions) | routes the conversation to the same server so the automatic prompt cache hits; Responses API uses body `prompt_cache_key` |42| `xai-sdk-version`, `xai-sdk-language` | auto (gRPC metadata from xai-sdk) | telemetry |4344## 4. Response headers (observed 2026-09-19)4546| Header | Where seen | Meaning |47|---|---|---|48| `x-request-id` | most inference and catalogue-detail responses; equals `chat.completion.id` | quote in bug reports (support@x.ai) |49| `x-ratelimit-limit-requests` / `x-ratelimit-remaining-requests` | chat completions, tokenize-text | per-minute request budget of the key for the model (7200 for grok-4.6/4.5, 1800 for grok-4.3/4.20/build) — undocumented |50| `x-ratelimit-limit-tokens` / `x-ratelimit-remaining-tokens` | chat completions | TPM budget (50M / 10M = documented Tier 0) — undocumented |51| `x-zero-data-retention: true\|false` | documented (FAQ) | ZDR state of the team |52| `Server-Timing: cfEdge;dur=…,cfOrigin;dur=…`, `CF-RAY` | all | Cloudflare edge; origin duration ≈ model latency |53| `Retry-After` | not documented, not observed | use exponential backoff on 429 |5455Not present: `x-ratelimit-reset-*`, version/organization headers.5657## 5. Error format5859Inference API (REST): `{"code": "<kebab-case code>", "error": "<message>"}` — e.g. `invalid-argument`, `not-found`, `unauthenticated:no-credentials`. Some validation failures return a **bare JSON string** (422 deserialization errors; the multi-agent-on-chat-completions 400). 405 returns an empty body. Management API: gRPC-style `{"code": 16, "message": "…", "details": []}`. gRPC: canonical status codes (`RESOURCE_EXHAUSTED` = rate limit).6061| HTTP | code (live) | Cause | Verified example |62|---|---|---|---|63| 400 | `invalid-argument` | bad body/URL, unsupported parameter, **incorrect API key** | `"Model grok-build-0.1 does not support parameter reasoningEffort."` · `"Incorrect API key provided. You can obtain an API key from https://console.x.ai."` · bare `"Multi Agent requests are not allowed on chat completions"` |64| 401 | `unauthenticated:no-credentials` | no Authorization header (inference); invalid bearer (Management API, `{code:16}`) | `"No credentials presented."` |65| 403 | — | missing ACL / disabled key / blocked team ("ask your team admin") | not triggered |66| 404 | `not-found` | unknown route or model not available to the team (same message for both; regional host without the model) | `"The model grok-2-image does not exist or your team <id> does not have access to it. If you believe this is a mistake, please contact support and quote your team ID and the model name."` |67| 405 | (empty) | wrong method | `DELETE /v1/models` |68| 415 | — | unsupported Content-Type | not triggered |69| 422 | (string) | field type/format invalid | `"Failed to deserialize the JSON body into the target type: text: invalid type: integer `123`, expected a string at line 1 column 33"` |70| 429 | (gRPC 8) | team RPS/TPM or per-key qps/qpm/tpm exceeded | not triggered; back off exponentially; Batch API bypasses limits |71| 202 | — | deferred completion not ready (`GET /v1/chat/deferred-completion/{id}`, empty body) | — |72| 5xx | — | check https://status.x.ai (RSS `/feed.xml`) | not triggered |7374Billing-side "errors": usage-guideline violations are still charged ($0.05 fee when caught before generation on Responses); exhausted prepaid credits with a $0 invoiced limit → requests rejected.7576## 6. gRPC ↔ HTTP code mapping (for xai-sdk users)7778| gRPC | HTTP | SDK handling |79|---|---|---|80| 3 INVALID_ARGUMENT | 400 | `grpc.RpcError`, `e.code() == grpc.StatusCode.INVALID_ARGUMENT` |81| 16 UNAUTHENTICATED | 401 | check key / host |82| 7 PERMISSION_DENIED | 403 | ACLs |83| 5 NOT_FOUND | 404 | model/route |84| 8 RESOURCE_EXHAUSTED | 429 | docs' backoff example catches exactly this |85| 4 DEADLINE_EXCEEDED | 504 | SDK default timeout 1620 s |86| 13 INTERNAL / 14 UNAVAILABLE | 500 / 503 | retry |87