# xAI (Grok) — errors

**Status:** DOCUMENTED + LIVE_VERIFIED (error shapes observed 2026-09-19) · **Last verified:** 2026-09-19

The full xAI error catalogue, header reference and retry guidance live in
[`docs/xai/authentication-headers-errors.md`](../xai/authentication-headers-errors.md); machine-readable records are in
`generated/errors.json` (`provider = "xai"`, 12 records) and `generated/headers.json`.

Quick facts observed live:

| Situation | HTTP | Body shape |
|---|---|---|
| Invalid API key | **400** (not 401) | `{"code": "...", "error": "Incorrect API key provided..."}` |
| Missing `Authorization` | 401 | `{"code": ..., "error": ...}` |
| Unknown model / retired id without redirect | 404 | `{"error": {"code": ..., "message": ...}}` |
| Schema/serde validation failure | 422 | bare `text/plain` string (serde error) |
| Retired feature (Live Search, `/v1/completions` sampling on reasoning models) | 410 / 400 | `{"code", "error"}` |
| Alpha-gated tool (`tool_search`) | 403 | `{"code", "error"}` "alpha users only" |
| Management API with an inference key | 401 | gRPC-style `{"code": 16, "message": ...}` |
| Rate limit | 429 | `{"code", "error"}` + `x-ratelimit-*` headers |

Retry policy used by the shared resilient client: never retry 400/401/403/404/410/422; back off on 429 (`x-ratelimit-reset-*` when present) and 5xx.