Errors

Gateway errors# (permalink)

These twelve are the complete set the gateway raises on its own. Anything else you see came from the model provider and passed straight through.

Order of checks# (permalink)

Knowing the order tells you what a status rules out. The gateway stops at the first failing check and never reaches the ones below it.

1. 01Path. A request with nothing after the base URL, or a path that does not resolve, gets 404 unknown_endpoint. This happens before authentication, so a 404 says nothing about your key.
2. 02Credential present. No Authorization: Bearer and no x-api-key gives 401 missing_api_key.
3. 03Key known. An unrecognised key gives 401 invalid_api_key.
4. 04Key usable. Suspended gives 403 key_suspended, past its expiry gives 403 key_expired.
5. 05Right surface. A credit key on the token base URL, or the reverse, gives 401 invalid_api_key again.
6. 06Funds. An empty balance gives 402 insufficient_credit, a spent budget gives 402 token_budget_exhausted.
7. 07Rate. A key over its requests-per-minute limit gives 429 rate_limit_exceeded, with a retry-after header holding the seconds left in the current window. This happens before the request body is read, so a throttled call costs nothing.
8. 08Model readable. Only now is the request body read. An inference call whose model field cannot be read, because the body is empty or is not valid JSON, gives 400 model_required rather than being forwarded unpriced.
9. 09Model allowed. A model outside the key’s allowlist gives 403 model_not_allowed.
10. 10Model servable. A model the gateway cannot serve, because the id is unknown or the model has been switched off centrally, gives 403 model_not_available. Both cases return the same body on purpose.
11. 11Forwarded. If the provider cannot be reached at all, 502 upstream_unavailable. Otherwise the provider’s own status is what you get.

Upstream failures# (permalink)

A request that passes every check is forwarded to the model provider, and the provider’s status and response body come back to you unchanged. So a 400 about an unsupported parameter, a 429 about rate limits, or a 529 about capacity originates there rather than here, and the message reads in the provider’s own words.

Response headers are filtered rather than mirrored. content-type and x-request-id are preserved, streamed responses also carry cache-control: no-cache, no-transform, and everything else is dropped. The one header the gateway adds itself is retry-after, on its own 429. Do not build logic on a header you have not seen documented here.

A 402 can also arrive this way, when the upstream account itself is short of funds. The distinction matters: if the usage checker shows your key still has balance or budget but calls keep returning 402, the problem is upstream and only your provider can clear it.

What to retry# (permalink)

Authentication, permission and billing failures are decisions, not accidents. Retrying them wastes time and makes rate limits worse. Only 429 and 5xx deserve another attempt.

const response = await fetch(url, init);

if (!response.ok) {
  const body = await response.json().catch(() => null);
  const code = body?.error?.code ?? "unknown_error";

  // Only 429 and 5xx are worth trying again.
  const retryable = response.status === 429 || response.status >= 500;

  throw Object.assign(new Error(body?.error?.message ?? response.statusText), {
    status: response.status,
    code,
    retryable,
  });
}

Then retry only what is retryable, with exponential backoff and jitter.

async function withRetry(send, attempts = 4) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await send();
    } catch (err) {
      if (!err.retryable || attempt >= attempts - 1) throw err;
      const wait = 500 * 2 ** attempt + Math.random() * 250;  // jittered backoff
      await new Promise((resolve) => setTimeout(resolve, wait));
    }
  }
}

• Cap the attempts. Four tries over roughly ten seconds is plenty for a transient upstream fault.
• Add jitter. Without it, every client that failed at the same moment retries at the same moment.
• On a 429, prefer the retry-after header over your own schedule when it is present. It is the exact number of seconds left in the current rate-limit window.
• Stop on 402 immediately, or you will hammer a key that has nothing left to spend.

What gets billed# (permalink)

Failures cost nothing, but they are not all recorded the same way.

Successful metadata calls are the one exception in the other direction. A GET /models reports no token usage, so it is neither billed nor listed. More detail on Checking usage.

Reporting a problem# (permalink)

When something needs a human, include:

• The x-request-id response header, when the provider supplied one.
• The HTTP status and the whole error object.
• The key prefix only, meaning the first characters such as kl_live_a1b2c3d4. Never send the whole key.
• The model id, whether you were streaming, and roughly when it happened.