Errors

When a request fails, the API returns an HTTP status code and a JSON body with an error object:

{
  "error": {
    "message": "Invalid value for 'temperature': number must be at most 2.",
    "type": "invalid_request_error",
    "param": "temperature",
    "code": "invalid_value"
  }
}

Field	Description
`message`	A human-readable description. Log it, but don’t parse it; its wording can change.
`type`	The error category, such as `invalid_request_error`.
`param`	The request parameter the error relates to, in dotted notation such as `messages[0].content`, or `null`.
`code`	A machine-readable code, or `null`. Use this in your error handling.

Status codes

Status	Meaning	Retry?
`400`	The request is invalid. Check `param` and `message`.	No. Fix the request.
`401`	The API key is missing, malformed, or not valid.	No. Fix the credential.
`402`	The organization has no credit or prepaid balance left.	No. Add credit or top up first.
`403`	The key is valid, but the caller isn’t allowed to make the request.	No. Resolve the access issue.
`404`	The requested model doesn’t exist or isn’t available to you.	No. See Models.
`409`	The organization’s billing isn’t ready to serve requests.	Only `tier_switch_pending`, after `Retry-After`.
`413`	The request body is too large.	No. Shorten the request.
`415`	The request body isn’t sent as JSON.	No. Set `Content-Type: application/json`.
`429`	A rate limit was exceeded.	Yes, after `Retry-After`. See Rate limits.
`502`	The model failed to produce a response.	Yes, with backoff.
`503`	The service is temporarily unavailable.	Yes, after `Retry-After` when present, otherwise with backoff.

Error codes

400: invalid request

These have error.type invalid_request_error.

`error.code`	Meaning
`invalid_json`	The body isn’t valid JSON.
`invalid_type`	A parameter has the wrong type.
`missing_required_parameter`	A required parameter or field is missing, such as `tool_call_id` on a `tool` message.
`invalid_value`	A parameter’s value is out of range or not allowed, or the conversation is out of order, such as a tool call without a result.
`context_length_exceeded`	The request is longer than the model accepts. The API doesn’t truncate it; shorten `messages` or lower `max_completion_tokens`.
`unsupported_value`	The parameter is supported only at a fixed value. See OpenAI compatibility.
`unsupported_parameter`	The parameter isn’t supported, or isn’t allowed in this context, such as `response_format.json_schema` with `type: "json_object"`.

401: authentication

These have error.type authentication_error.

`error.code`	Meaning
`missing_credentials`	No `Authorization` header was sent.
`invalid_authorization_header`	The header isn’t of the form `Bearer <key>`.
`invalid_api_key`	The key is incorrect, disabled, or revoked.
`missing_project_scope`	The credential isn’t associated with a project.
`invalid_session`	The credential’s session isn’t valid.

402: payment required

These have error.type permission_error. Resolve them in the billing settings of the Reflection platform, then retry.

`error.code`	Meaning
`insufficient_credits`	The organization has no remaining credits.
`prepaid_balance_exhausted`	The organization’s prepaid balance is used up. Top it up to resume requests.

A used-up daily token allowance can also return insufficient_credits instead of a 429. The allowance renews at 00:00 UTC.

403: permission

These have error.type permission_error.

`error.code`	Meaning
`organization_membership_required`	The key’s user isn’t a member of the organization.
`account_restricted`	The user, organization, or API key is restricted. Contact support.
`payment_method_required`	The organization must verify a credit card in Billing on the Reflection platform before using API keys.
`plan_access_denied`	The organization’s plan doesn’t include the kind of credential used.

404: not found

`error.code`	Meaning
`model_not_found`	The model doesn’t exist or isn’t available to you. List models to see the ones you can use.

409: billing conflict

These have error.type permission_error.

`error.code`	Meaning
`tier_switch_pending`	The organization’s billing tier is changing. Wait for the number of seconds in `Retry-After`, then retry.
`billing_setup_required`	The organization’s billing setup is incomplete. Finish setup in Billing on the Reflection platform before retrying. The response includes `x-should-retry: false`.

413: request too large

`error.code`	Meaning
`request_too_large`	The request body exceeds the maximum size.

415: unsupported media type

`error.code`	Meaning
`unsupported_media_type`	The request has a body but no `Content-Type: application/json` header. The OpenAI SDKs set it for you.

429: rate limit

These have error.type rate_limit_error and code rate_limit_exceeded, whichever limit was exceeded; message says which one. See Rate limits. Wait for Retry-After, when present, then retry. When a daily limit or allowance is spent, the response also includes x-should-retry: false, because retrying can’t succeed until it renews at 00:00 UTC. Responses can also report your remaining capacity in rate limit headers.

502: bad gateway

The model failed to produce a response. These have error.type upstream_unavailable_error and a null code.

503: unavailable

These have error.type api_error.

`error.code`	Meaning
`infrastructure_rate_limit_exceeded`	Inference capacity is temporarily exhausted. The response includes `Retry-After`.
`inference_capacity_unavailable`	The model’s capacity is temporarily unavailable. The response includes `Retry-After`.
`billing_provisioning_pending`	The organization’s billing setup is still in progress. The response includes `Retry-After`.
`authentication_unavailable`, `enforcement_unavailable`, `rate_limit_unavailable`, `payment_readiness_unavailable`	A service needed to accept the request is temporarily unavailable.

Request IDs

Every response, except a CORS preflight response, has an x-request-id header that identifies the request, and an x-server-request-id header with the same value. The server generates the ID; it is independent of any request ID you send. Log it with errors, and include it when you contact support. The OpenAI SDKs read the header for you:

import openai

try:
    completion = client.chat.completions.create(
        model="Beam-501B-A23B",
        messages=[{"role": "user", "content": "Hello"}],
    )
    print(completion._request_id)
except openai.APIStatusError as e:
    print(e.status_code, e.request_id)

import OpenAI from "openai";

try {
  const completion = await client.chat.completions.create({
    model: "Beam-501B-A23B",
    messages: [{ role: "user", content: "Hello" }],
  });
  console.log(completion._request_id);
} catch (err) {
  if (err instanceof OpenAI.APIError) console.log(err.status, err.requestID);
  else throw err;
}

With cURL, add -i to print the response headers.

Retrying

Retry 429, 502, and 503 responses, 409 responses with code tier_switch_pending, and network errors, with exponential backoff and jitter. When a response has a Retry-After header, wait at least that many seconds. Don’t retry a response that has an x-should-retry: false header, and don’t retry other 4xx responses without changing the request. The OpenAI SDKs retry these errors automatically, twice by default, and don’t retry a response with x-should-retry: false. To change that, set max_retries:

client = OpenAI(
    base_url="https://api.reflection.ai/openai/v1",
    api_key=os.environ["REFLECTION_API_KEY"],
    max_retries=5,
)

const client = new OpenAI({
  baseURL: "https://api.reflection.ai/openai/v1",
  apiKey: process.env.REFLECTION_API_KEY,
  maxRetries: 5,
});

Get started

Coding agents

Mirror CLI

Guides

Resources

Status codes

Error codes

400: invalid request

401: authentication

402: payment required

403: permission

404: not found

409: billing conflict

413: request too large

415: unsupported media type

429: rate limit

502: bad gateway

503: unavailable

Request IDs

Retrying

​Status codes

​Error codes

​400: invalid request

​401: authentication

​402: payment required

​403: permission

​404: not found

​409: billing conflict

​413: request too large

​415: unsupported media type

​429: rate limit

​502: bad gateway

​503: unavailable

​Request IDs

​Retrying

Status codes

Error codes

400: invalid request

401: authentication

402: payment required

403: permission

404: not found

409: billing conflict

413: request too large

415: unsupported media type

429: rate limit

502: bad gateway

503: unavailable

Request IDs

Retrying