Errors

1. By status code

Locate the code in the table first, then read the matching section.

1.1 What do I do about a 400?

Usually invalid_request_error or model_not_found. Validate the JSON and required fields, confirm the model ID and endpoint came from the current key's GET /v1/models, and check the channel and model access.

invalid_callback_url means POST /v1/router/task/create received a callback_url that is not a public HTTPS URL. HTTP is accepted only on a local deployment. The value is also rejected when it is longer than 2048 characters, contains a username or password, or points at loopback, a private network, link-local, metadata, or localhost. No task is created.

Do not retry.

1.2 What do I do about a 401?

Authentication failed. This can be an invalid platform API key, or an upstream 401 passed through as-is. Check that the API key exists, is still enabled, and is correctly formatted (Authorization: Bearer sk-..., x-api-key: sk-...; Gemini native endpoints and GET /v1/models also accept x-goog-api-key or ?key=). error.code missing_key means no key was sent. conflicting_keys is returned only by those endpoints when credential sources disagree, or when one presented source is empty while another has a key. invalid_key means the key is unknown or disabled.

Do not retry — fix the request first.

1.3 What do I do about a 402?

Your balance is insufficient or the API key reached its spend limit. Top up, or switch to a key without an exhausted limit.

Do not retry.

1.4 What do I do about a 424 with error.code provider_error?

An upstream infrastructure failure. The gateway has normalized away the provider details and hands you a neutral error plus a request ID.

Record that ID (it's in the error message, or read the X-AIToken-Request-Id / X-OneAPI-Request-Id response header), then retry only through bounded application-level exponential backoff with jitter.

1.5 What do I do about a 429?

Inspect error.code and the response headers:

• account_rpm_limit: back off using RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset.
• account_concurrency_limit: wait for Retry-After.
• No account-limit code or headers: you may have sent the exact same request four times within 10 seconds, or received an upstream 429.

See Billing & limits.

1.6 What do I do about a 5xx, or a 504 from the image endpoints?

upstream_error, api_error, internal_error, and timeout_error are recoverable and may be retried.

On a 504 from the image endpoints, do not resubmit — the task is still running, so keep polling its task_id.

2. Retries & failed streams

2.1 Which errors should I never retry?

400, 401, and 402 — fix the request or top up instead.

The retryable ones are 424, 429, and recoverable 5xx, always with exponential backoff, jitter, and a bounded attempt count.

2.2 My stream cut off mid-response — how do I tell it failed?

Treat both of these as failures:

1. Receiving the protocol's provider_error terminal event.
2. A stream that ends without that protocol's normal completion event.

The reason is that when the upstream stream fails after HTTP 200 has been committed, the status can no longer become 424. While the connection is still writable, the gateway emits exactly one provider_error event carrying the request ID, then closes the stream. If the client or transport is already gone, that event can't be delivered and only the server-side log remains.

When contacting support, provide the request ID from the event body or the X-AIToken-Request-Id / X-OneAPI-Request-Id response header.

3. Error envelopes

Envelopes vary by endpoint family:

Common LLM type values are invalid_request_error, model_not_found, authentication_error, insufficient_quota, rate_limit_error, api_error, and internal_error; Anthropic and Gemini return their own native envelopes. Media tasks do not use the LLM account limits or the retired shared per-key/per-IP allowance.

The full reference is in Error codes.