Errors

Errors use the OpenAI error envelope, so existing client error handling keeps working:

{
  "error": {
    "message": "Not Found",
    "type": "not_found_error",
    "code": "404"
  }
}

type follows the HTTP status, so you can branch on either. Every response, errors included, carries an x-request-id header. Log it with the error and quote it in any support request: it is how we find the call.

Types by status

Status	type
400, 422	invalid_request_error
401	authentication_error
403	permission_error
404	not_found_error
408, 504	timeout_error
429	rate_limit_error
500	internal_server_error
502	api_error
503	service_unavailable_error

What each status means

Status	Cause	What to do
400	Malformed request, or a model id that is not in the catalog. The message points you to /v1/models.	Fix the request. Do not retry as is.
401	The key is invalid or revoked.	Check the value; create a new key if needed.
401	The account is out of credit, so every key is blocked. The message says the key is blocked.	Top up on the Billing page. See Credits & budgets.
403	The key is not allowed to call this model, or the path is not part of the API.	Check the key’s allowed models and the endpoint list.
404	Unknown path.	Check the URL.
408, 504	The provider did not answer in time.	Retry once.
429	Rate limit reached, or the key’s budget is used up.	Back off and retry for a rate limit; top up or wait for the reset for a budget. See Rate limits.
500, 502, 503	The gateway or the provider failed.	Retry once with a short delay.

Provider errors

When the provider itself rejects a request, the gateway returns the provider’s HTTP status and type, keeps the retry-after header if there was one, and replaces the provider’s message with a neutral one:

{
  "error": {
    "message": "The upstream model provider rejected the request (HTTP 400). Request id: 7f3c...",
    "type": "invalid_request_error",
    "code": "400"
  }
}

The request id in the message is the same as the x-request-id header.

Handling errors with the OpenAI SDKs

The SDKs raise a typed exception per status and expose the request id, so the usual OpenAI error handling applies without change:

Python

import openai

try:
    reply = client.chat.completions.create(
        model="gpt-4.1-mini",
        messages=[{"role": "user", "content": "Hello"}],
    )
except openai.RateLimitError as e:
    # 429: rate limit or key budget. Back off, or stop if the message mentions the budget.
    print("Rate limited:", e.message, "request id:", e.request_id)
except openai.AuthenticationError as e:
    # 401: bad key, or the account is out of credit.
    print("Auth failed:", e.message, "request id:", e.request_id)
except openai.APIStatusError as e:
    print(e.status_code, e.message, "request id:", e.request_id)

JavaScript

import OpenAI from "openai";

try {
  const reply = await client.chat.completions.create({
    model: "gpt-4.1-mini",
    messages: [{ role: "user", content: "Hello" }],
  });
} catch (e) {
  if (e instanceof OpenAI.RateLimitError) {
    // 429: rate limit or key budget. Back off, or stop if the message mentions the budget.
    console.error("Rate limited:", e.message, "request id:", e.requestID);
  } else if (e instanceof OpenAI.AuthenticationError) {
    // 401: bad key, or the account is out of credit.
    console.error("Auth failed:", e.message, "request id:", e.requestID);
  } else if (e instanceof OpenAI.APIError) {
    console.error(e.status, e.message, "request id:", e.requestID);
  } else {
    throw e;
  }
}