Recover from API errors and limits

Start with the HTTP status, public error code, request-id header and, when present, retry-after and x-should-retry. OpenAI-compatible endpoints return an error object; Messages uses an Anthropic-shaped error envelope. A diagnostic record can include time, endpoint, selected public model ID and these safe values. Keep the API key, prompt, response, browser cookie and raw internal error out of logs and support reports.

Read the code, not just the HTTP status

OpenAI-compatible errors contain error.message, error.type, error.code, and request_id. Messages errors contain type: "error", nested error.type and error.message, and request_id. The request-id and x-request-id headers help support correlate the response. Client logic should use the HTTP status, public code, and retry headers; the human-facing message can change.

You may send a UUID in x-request-id; the Gateway preserves it or generates a new UUID for a missing or invalid value. Terminal stream errors carry the same request_id: at the top level of Responses response.failed, Messages error, and the Chat Completions error object. This identifies the HTTP request; the response or chunk id still identifies the logical answer. On an idempotent failure replay, the body retains the original request ID while the HTTP headers identify the replay request. Prefer the body's ID for support correlation.

Responses response.failed.code contains the public UnlimGPT code; response.error.code retains the SDK error family.

For example, temporary model unavailability on Responses returns HTTP 503 and the safe provider_unavailable code:

{
  "error": {
    "message": "The model is temporarily unavailable.",
    "type": "server_error",
    "param": null,
    "code": "provider_unavailable"
  },
  "request_id": "01992b95-663e-76e2-8f05-3ff3363c5f90"
}

The ID illustrates the format only; retain the ID from your own response. Messages maps the same code to error.type: "overloaded_error". HTTP 503 alone does not guarantee a safe retry: check x-should-retry, retry-after, and the logical request's outcome.

For request rate limits, read x-ratelimit-limit-requests, x-ratelimit-remaining-requests, and x-ratelimit-reset-requests. Anthropic-compatible clients receive the same limit in anthropic-ratelimit-requests-* headers, with a different reset-time format. These describe your organization's request limit. For a long subscription limit, an OpenAI-compatible response may also include error.resets_at alongside retry-after.

Reproduce safely

Use the free model catalog to check authentication and model visibility before repeating a paid generation. Confirm that the key belongs to the selected organization and has the permissions shown in API keys. If the failure came from a stream, read its final event: the initial HTTP 200 may precede a terminal error. Preserve an idempotency key and unchanged body while investigating an uncertain outcome.

Choose the next action

• HTTP 401 authentication_required: check the Bearer header, key state and expiry using authentication. A browser session is not an API key.
• HTTP 400 invalid_request: correct malformed JSON, conflicting fields, or unsupported request content. The same code may accompany HTTP 404 for a missing resource; inspect both values.
• HTTP 402 insufficient_credits: inspect credits and limits. Wait for an applicable grant or change the account state before sending another paid request.
• HTTP 403 early_access_required or permission_denied: check organization access and key permissions. Switching the model will not grant missing account access.
• HTTP 403 account_suspended: account access is suspended. Retain the request ID for support; retrying with another key will not remove the restriction.
• HTTP 404 model_not_found: choose a canonical ID visible in the catalog, rather than a display name or an assumed ID.
• HTTP 404 not_found: check the endpoint address and public operation ID; an unknown or another organization's run is not disclosed.
• HTTP 409 idempotency_conflict: follow the replay procedure. Retry only when x-should-retry is true and the body remains unchanged.
• HTTP 413 request_too_large: reduce the body below 4 MiB, including encoded media, before trying again.
• HTTP 429 rate_limit_exceeded, concurrency_limit_exceeded, or usage_limit_exceeded: inspect retry-after and x-should-retry. Request-rate and concurrency limits may allow a retry after a wait; a plan usage limit needs its reset or a plan change.
• unsupported_capability or context_length_exceeded: remove an unsupported requested feature or shorten the input before making a new logical request.
• HTTP 503 provider_unavailable: the model is temporarily unavailable. Retain the request ID and check model availability; if retry is allowed, keep the same idempotency key and body.
• HTTP 504 generation_timeout: the logical request exceeded its deadline. Inspect the terminal outcome and Activity before retrying to avoid a second generation.
• HTTP 500 internal_error: retain the request ID for support; x-should-retry: false forbids an automatic retry.
• request_cancelled: the client or user cancelled the operation; the connection may close without a new HTTP response. This is a terminal outcome, not a reason to retry a paid generation automatically.

x-should-retry: false forbids an automatic retry of that operation. For true, wait for retry-after and keep the original Idempotency-Key and request body. A missing header alone is not permission for an endless retry loop: bound both attempts and the client's overall deadline. For streams, read the native terminal event because HTTP 200 only confirms that transmission began.

Verify recovery

After correcting the cause, start with one bounded request using a model returned by the catalog. A successful non-streaming call has a completed response; for SSE, require its native terminal event. If the outcome remains unclear, compare the same organization's API Activity by time and endpoint, and give support only the public request ID and safe code. Follow connection troubleshooting for transport failures. Consult the Responses, Chat Completions, or Messages guide for protocol context.