Grok API
← All documentation

Grok API errors

View as Markdown

Updated:

Grok AI: Grok API HTTP error codes, their causes, and ways to resolve problems.

Error response format

Grok API Dev returns errors in an OpenAI-compatible format. The response is an error object with code, message, and type fields.

JSON
{
  "error": {
    "message": "Invalid model ID",
    "type": "invalid_request_error",
    "code": "invalid_model"
  }
}

Grok API error codes

The 400, 401, 403, 404, 405, 415, 422, and 429 codes match the official xAI debugging reference. The standard 5xx cases below cover temporary gateway and upstream failures defensively.

CodeCauseWhat to doRetry
400
Bad Request
Invalid JSON, argument, or request body. A malformed key can also surface here.Check JSON, required fields, value types, and the Authorization header.No, not until fixed
401
Unauthorized
The API key is missing, invalid, or sent in the wrong format.Send Authorization: Bearer sk-lg-... and remove accidental whitespace.No
403
Forbidden
The key is recognized, but the resource is not permitted.Check account and model access. Contact support if the request is valid.No
404
Not Found
The base URL, endpoint, or model ID is wrong.Compare https://api.llm-gate.tech/v1, /v1/chat/completions, and the model name.No
405
Method Not Allowed
The endpoint received the wrong HTTP method.Use the documented method, normally POST for generation.No
415
Unsupported Media Type
The body is empty or Content-Type: application/json is missing.Send a JSON body and the correct Content-Type.No
422
Unprocessable Entity
JSON parsed, but a field failed schema validation.Check messages structure, parameter types, and allowed values.No
429
Too Many Requests
The current rate limit was exceeded.Reduce concurrency and request frequency. Honor Retry-After.Yes, with backoff and jitter
500
Internal Server Error
A temporary internal service failure occurred.Keep the request ID and retry a limited number of times.Yes
502/503/504
Gateway or upstream
The gateway or upstream is unavailable or timed out.Check the status page and retry with increasing delays.Yes

Safe retries

  • Do not retry 400, 401, 403, 404, 405, 415, or 422 until the request is fixed.
  • Cap attempts and add random jitter so clients do not retry together.
  • Honor Retry-After when present. Otherwise use exponential backoff.
  • Plan idempotency for operations with side effects. A retry can otherwise perform an action twice.
JavaScript
const retryable = new Set([429, 500, 502, 503, 504]);

function retryAfterMs(value) {
  if (!value) return null;
  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
  const date = Date.parse(value);
  return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
}

async function fetchWithRetry(url, init, maxAttempts = 4) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(url, init);
    if (!retryable.has(response.status) || attempt === maxAttempts - 1) {
      return response;
    }

    const retryAfter = retryAfterMs(response.headers.get("retry-after"));
    const backoff = 500 * 2 ** attempt;
    const jitter = Math.random() * 250;
    const delayMs = retryAfter !== null
      ? retryAfter
      : backoff + jitter;

    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }

  throw new Error("unreachable");
}