[
 {
  "provider": "xai",
  "http_status": 400,
  "type": "invalid-argument",
  "code": "invalid-argument",
  "category": "client",
  "message_semantics": "Bad request body/URL, unsupported parameter for the model, or an incorrect API key (xAI returns 400 not 401 for a malformed/unknown key). Body shape: {\"code\": \"invalid-argument\", \"error\": \"<message>\"}. Some 400s are a bare JSON string (multi-agent on chat completions).",
  "retryable": false,
  "recommended_action": "Fix the request; check the model page for supported parameters (e.g. reasoning_effort only on grok-4.6/4.5/4.3, multi-agent only on /v1/responses).",
  "source": "https://docs.x.ai/developers/debugging",
  "observed_live": true,
  "live_examples": [
   "POST /v1/chat/completions grok-4.20-0309-non-reasoning reasoning_effort=low -> {\"code\":\"invalid-argument\",\"error\":\"Model grok-4.20-0309-non-reasoning does not support parameter reasoningEffort.\"}",
   "same for grok-4.20-0309-reasoning and grok-build-0.1",
   "POST /v1/chat/completions grok-4.20-multi-agent-0309 -> \"Multi Agent requests are not allowed on chat completions\" (plain JSON string body)",
   "GET /v1/models with bogus bearer -> {\"code\":\"invalid-argument\",\"error\":\"Incorrect API key provided. You can obtain an API key from https://console.x.ai.\"}"
  ]
 },
 {
  "provider": "xai",
  "http_status": 401,
  "type": "unauthenticated",
  "code": "unauthenticated:no-credentials",
  "category": "auth",
  "message_semantics": "No Authorization header. Note: an INVALID key yields 400 invalid-argument on the inference API, while the Management API returns 401 with a gRPC-style body {\"code\": 16, \"message\": \"Invalid bearer token. Please ensure you use a valid management key.\", \"details\": []} (16 = UNAUTHENTICATED).",
  "retryable": false,
  "recommended_action": "Send Authorization: Bearer <XAI_API_KEY>; use a Management key on management-api.x.ai.",
  "source": "https://docs.x.ai/developers/debugging",
  "observed_live": true,
  "live_examples": [
   "GET /v1/models (no auth) -> {\"code\":\"unauthenticated:no-credentials\",\"error\":\"No credentials presented.\"}",
   "GET https://management-api.x.ai/auth/management-keys/validation with inference key -> 401 {code:16}"
  ]
 },
 {
  "provider": "xai",
  "http_status": 403,
  "type": "forbidden",
  "code": "permission-denied (assumed)",
  "category": "auth",
  "message_semantics": "Key lacks an ACL (api-key:endpoint:<name> / api-key:model:<name>), key disabled/blocked, team blocked, or ZDR/feature restriction. Docs: 'Ask your team admin for permission.'",
  "retryable": false,
  "recommended_action": "Check GET /v1/api-key (acls, api_key_blocked, api_key_disabled, team_blocked); have an admin fix ACLs via console or Management API.",
  "source": "https://docs.x.ai/developers/debugging",
  "observed_live": false,
  "live_examples": []
 },
 {
  "provider": "xai",
  "http_status": 404,
  "type": "not-found",
  "code": "not-found",
  "category": "client",
  "message_semantics": "Unknown path, or model 'does not exist or your team <team_id> does not have access to it' (the same message covers non-existent and restricted models -> never conclude non-existence). Regional endpoints return 404 for models they do not serve (e.g. grok-latest on us.api.x.ai).",
  "retryable": false,
  "recommended_action": "Check the id against GET /v1/models on the SAME base URL; contact support with team id + model name if access is expected.",
  "source": "https://docs.x.ai/developers/debugging",
  "observed_live": true,
  "live_examples": [
   "GET /v1/models/grok-2-image -> {\"code\":\"not-found\",\"error\":\"The model grok-2-image does not exist or your team c5cb…7d93 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.\"}",
   "GET /v1/models/grok-voice-think-fast-2.0 -> 404 (voice models are not in the catalogue)",
   "GET /v1/embedding-models/grok-embedding-small -> 404",
   "POST /v1/chat/completions model=grok-2-image -> 404 same body"
  ]
 },
 {
  "provider": "xai",
  "http_status": 405,
  "type": "method-not-allowed",
  "code": null,
  "category": "client",
  "message_semantics": "HTTP method not supported by the path (e.g. POST to a GET-only endpoint). Empty body observed.",
  "retryable": false,
  "recommended_action": "Check the method in the REST reference.",
  "source": "https://docs.x.ai/developers/debugging",
  "observed_live": true,
  "live_examples": [
   "DELETE /v1/models -> 405 with empty body"
  ]
 },
 {
  "provider": "xai",
  "http_status": 415,
  "type": "unsupported-media-type",
  "code": null,
  "category": "client",
  "message_semantics": "Wrong Content-Type on a POST endpoint.",
  "retryable": false,
  "recommended_action": "Send application/json (or multipart/form-data where required).",
  "source": "https://docs.x.ai/developers/debugging",
  "observed_live": false,
  "live_examples": []
 },
 {
  "provider": "xai",
  "http_status": 422,
  "type": "unprocessable-entity",
  "code": null,
  "category": "client",
  "message_semantics": "A field of the POST body has an invalid format/type. Body is a plain JSON string from the deserializer (serde-style), not the {code,error} object.",
  "retryable": false,
  "recommended_action": "Fix field types (message names the field, line and column).",
  "source": "https://docs.x.ai/developers/debugging",
  "observed_live": true,
  "live_examples": [
   "POST /v1/tokenize-text {text: 123} -> \"Failed to deserialize the JSON body into the target type: text: invalid type: integer `123`, expected a string at line 1 column 33\""
  ]
 },
 {
  "provider": "xai",
  "http_status": 429,
  "type": "too-many-requests",
  "code": "resource-exhausted (gRPC RESOURCE_EXHAUSTED)",
  "category": "rate_limit",
  "message_semantics": "Per-model RPS or TPM limit of the team exceeded, or per-key qps/qpm/tpm cap set via the Management API, or prepaid credits depleted with a $0 invoiced-billing limit (requests 'automatically rejected' - status code for this case not documented).",
  "retryable": true,
  "backoff": "exponential (docs example: 2**attempt seconds, 5 retries); no Retry-After documented",
  "recommended_action": "Back off; spread load; raise tier via spend or console request; move bulk work to the Batch API (does not count towards rate limits).",
  "source": "https://docs.x.ai/developers/rate-limits",
  "observed_live": false,
  "live_examples": []
 },
 {
  "provider": "xai",
  "http_status": 500,
  "type": "internal",
  "code": null,
  "category": "server",
  "message_semantics": "Server-side failure (not enumerated in docs; check https://status.x.ai and the RSS feed https://status.x.ai/feed.xml).",
  "retryable": true,
  "backoff": "exponential with jitter",
  "recommended_action": "Retry; report persistent failures to support@x.ai with x-request-id.",
  "source": "https://docs.x.ai/developers/debugging",
  "observed_live": false,
  "live_examples": []
 },
 {
  "provider": "xai",
  "http_status": 202,
  "type": "accepted (not an error)",
  "code": null,
  "category": "async",
  "message_semantics": "GET /v1/chat/deferred-completion/{request_id}: result not ready yet (empty body). Deferred results can be fetched exactly once within 24 h.",
  "retryable": true,
  "recommended_action": "Poll with backoff.",
  "source": "https://docs.x.ai/developers/advanced-api-usage/deferred-chat-completions",
  "observed_live": false,
  "live_examples": []
 },
 {
  "provider": "xai",
  "http_status": 200,
  "type": "usage-guideline-violation (billing event, not an HTTP error)",
  "code": null,
  "category": "policy",
  "message_semantics": "Requests judged to violate usage guidelines are still charged; violations caught before generation on the Responses API incur a flat $0.05 fee.",
  "retryable": false,
  "recommended_action": "Review content policy.",
  "source": "https://docs.x.ai/developers/pricing",
  "observed_live": false,
  "live_examples": []
 },
 {
  "provider": "xai",
  "http_status": null,
  "type": "grpc-status-mapping",
  "code": "gRPC codes",
  "category": "reference",
  "message_semantics": "gRPC API (api.x.ai:443, xai_api.* services) surfaces canonical gRPC status codes; the Management API's REST error body {code, message, details} uses the same numbering. Mapping used by the SDK/docs: 3 INVALID_ARGUMENT -> 400; 16 UNAUTHENTICATED -> 401; 7 PERMISSION_DENIED -> 403; 5 NOT_FOUND -> 404; 8 RESOURCE_EXHAUSTED -> 429 (rate limit; xai-sdk docs catch grpc.StatusCode.RESOURCE_EXHAUSTED); 13 INTERNAL -> 500; 14 UNAVAILABLE -> 503; 4 DEADLINE_EXCEEDED -> 504 (SDK default timeout 1620 s).",
  "retryable": null,
  "recommended_action": "In xai-sdk, catch grpc.RpcError and inspect e.code().",
  "source": "https://docs.x.ai/developers/rate-limits",
  "observed_live": true,
  "live_examples": [
   "management-api 401 body {\"code\": 16, \"message\": \"Invalid bearer token…\", \"details\": []}"
  ]
 }
]