HTTP error codes

Every error from the Glexir gateway uses OpenAI's error shape, so OpenAI-compatible clients handle it without changes. This page lists every status, type and code the gateway returns, what causes it, and how to fix it.

Error shape

{
  "error": {
    "message": "Your Glexir credit balance is too low (available $0.42, this request needs up to $1.10). Add credits or enable auto-recharge.",
    "type": "insufficient_quota",
    "param": null,
    "code": "credit_balance_exhausted"
  }
}

Every response, success or error, carries an x-request-id header (req_...). Include it when you contact support.

Handle errors in code

Branch on status and code, not on message.

import Glexir, { APIConnectionError, APIError, RateLimitError } from "@glexir/sdk";

const glexir = new Glexir({ apiKey: process.env.GLEXIR_API_KEY });

try {
  const response = await glexir.responses.create({ model: "gpt-5.4-mini", input: "Say hello." });
  console.log(response.output_text);
} catch (err) {
  if (err instanceof APIConnectionError) {
    // No HTTP response: network failure or timeout. Already retried.
    console.error("connection problem", err.message);
  } else if (err instanceof RateLimitError) {
    console.error("429", err.code, err.headers?.get("retry-after"));
  } else if (err instanceof APIError && err.status === 402) {
    console.error("out of credit or over a spend limit:", err.code, err.param);
  } else if (err instanceof APIError) {
    console.error(err.status, err.type, err.code, err.param, err.requestID);
  } else {
    throw err;
  }
}

APIConnectionError extends APIError, so test for it first. The SDK has no class for 402 or 413; those are plain APIError instances. See Errors & retries for the full class list and retry rules.

Summary

You are not charged for a request that ends in an error response. The credit reserved for it is released. Streams are the exception: see Errors during a stream.

400 Bad request

type is invalid_request_error.

Batch input files are checked line by line when you upload them. A failing line returns 400 with param: "file", a message that starts with Batch line N:, and the code of the underlying problem (for example unsupported_on_glexir). Other upload errors: purpose must be user_data or batch, and batch files must end in .jsonl, contain at most 50,000 requests, use one model and one URL, and must not stream.

Errors that OpenAI returns for your request's content (for example an invalid parameter value) are passed through with OpenAI's status, type, code and param. Any OpenAI organization or project identifiers in the message are redacted.

401 Authentication failed

A revoked key can keep working for up to 30 seconds while the gateway's key cache expires. Do not retry a 401; the SDK does not.

402 Payment required

Glexir is prepaid. Before a request goes upstream, the gateway reserves its worst-case cost from your balance. A 402 means that reservation was refused. type is insufficient_quota.

The reservation is an upper bound. When you set no output cap, the gateway reserves for 32,000 output tokens, so a small balance can be refused even for a short request. After the request finishes you are charged the actual usage and the rest is released. See Credits & billing.

Neither SDK retries a 402. Retrying will not help until you add credit or change the limit.

403 Forbidden

404 Not found

type is invalid_request_error.

409 Conflict

type is invalid_request_error.

The @glexir/sdk and the official OpenAI SDKs retry every 409 up to maxRetries times. That helps with idempotency_request_in_progress but not with the other two codes.

413 Payload too large

type is invalid_request_error.

422 Unprocessable entity

429 Too many requests

type is rate_limit_error.

The requests-per-minute limit counts every authenticated request, including ones that later fail. Limits are per organization, not per key. See Rate limits & spend limits.

5xx Server and upstream errors

All of these are safe to retry with backoff, and both SDKs retry them by default. If they persist, contact support with the x-request-id.

Upstream retries and failover

The gateway retries upstream failures (408, 429 and 5xx responses, and connection errors) before it returns an error to you:

• Stateless requests can be served by another upstream route. These are Chat Completions requests that don't reference stored files, embeddings, transcriptions and translations, model lookups, and input token counts.
• Requests tied to stored state stay on the route that holds that state and get one more attempt there. This covers every POST /v1/responses (responses carry encrypted reasoning bound to where they were created), anything that uses previous_response_id, a conversation or a stored file, and every file, batch and conversation endpoint.

On a retry to the same route, if the upstream asks for a delay longer than 10 seconds, the gateway does not wait. It returns the error so your client can decide.

Errors during a stream

Once a stream has started, the HTTP status is already 200. An error then arrives as an SSE error event in the same shape:

event: error
data: {"error":{"message":"The upstream stream went silent and was closed.","type":"server_error","code":"stream_timeout","param":null}}

Error events from the upstream stream itself are passed through unchanged. In @glexir/sdk, a mid-stream error is thrown as an APIError whose status is undefined, so check err.code. Neither SDK retries a stream after it has started.

Billing for a text stream that ends early: if the upstream reported usage, you pay that usage. If the stream ended without a usage report, you are charged an estimate of the input tokens only. A transcription stream without a usage report is charged by the audio's duration.

SDK error classes

@glexir/sdk maps statuses to classes. All extend APIError, which extends GlexirError.

Two errors do not come from the API. parse() throws LengthFinishReasonError when the output hit the token limit and ContentFilterFinishReasonError when the content filter cut it off. Both extend GlexirError.