Troubleshooting

When a call fails, read the error message and match it below. Most problems are solvable from this page alone.

This page is ordered by real-world frequency — the first two categories account for more than half of all failures, and neither of them is a problem with your configuration.

First: whose problem is it

Upstream errors (most common)

What these have in common: the platform forwarded your request successfully — the problem is on the model provider's side. Your key, balance and parameters are all fine.

Upstream rate limiting

Typical error text:

You exceeded your current quota, please check your plan and billing details.
You have exceeded your current request limit.
Rate limit exceeded. Please wait and try again, or upgrade your API plan.
Request rate increased too quickly.

The upstream provider is rate-limiting the platform's account, usually when a popular model is being called heavily.

What to do:

1. Add exponential backoff — by far the most effective fix. Retrying immediately makes it worse.
2. Make sure your key uses Smart routing. Smart routing has a circuit breaker and moves off a rate-limited route automatically; pinning a supplier gives that up.
3. If it persists, switch to a comparable model to spread the load, or contact support.

Upstream service failures

Typical error text:

bad response status code 524
upstream connect error or disconnect/reset before headers
service unavailable
internal server error
status_code=500, The product is not activated...

A transient outage, timeout or gateway error at the provider.

What to do: retry. 524 and upstream connect error usually mean the upstream was too slow or dropped the connection — long outputs hit this more often, so switching to streaming (stream: true) both reduces timeouts and improves perceived latency.

Invalid request parameters

Typical error text:

invalid_request_error
invalid_parameter_error
unsupported_parameter
unknown_parameter
status_code=404, Resource not found

Something is wrong with the request body. Check in this order:

1. Content-Type: application/json is present;
2. The JSON is syntactically valid (no trailing commas, matched quotes);
3. Required fields are there (model, messages);
4. The parameter is supported by that model — unsupported_parameter / unknown_parameter mean you sent something the model does not recognise. Providers differ; passing OpenAI-specific parameters straight to another vendor's model is the usual cause;
5. Resource not found is usually a misspelled model name, or calling an endpoint the model does not serve (e.g. hitting the image endpoint with a chat model).

Quota

Insufficient quota

Your account balance has run out. Top up or redeem on the Wallet page; service resumes immediately.

If you are sure you topped up recently, check the Limited-time grants card — an expiring grant reduces the total balance. See Limited-time grants.

This token's quota is exhausted

The key's own cap is used up — not an account balance problem. Edit the key to raise its quota or enable unlimited.

See the distinction.

Authentication

Invalid token / Token not provided

The platform could not recognise your key.

• Check the header format: Authorization: Bearer sk-xxxxxxxx, with a single space after Bearer.
• Check for stray spaces, newlines or quotes — copying via chat apps often introduces invisible characters.
• Check whether the key was deleted. Deletion is irreversible; create a new key.
• Confirm the domain you are calling matches the site where the key was created. A key created on site A does not work on site B.

This token has expired

The key passed its expiration time. Edit it under API Keys to extend the expiry or set it to never expire.

Token status unavailable

The key was disabled. Re-enable it under API Keys.

Requests rejected although the key looks fine

Check whether the key has an IP whitelist configured.

1.2.3.4
5.6.7.8
203.0.113.0/24

Also note that in containers, serverless platforms or behind an egress gateway, your real outbound IP may differ from what you expect — and may change. If unsure, clear the whitelist to confirm this is the cause, then add the correct ranges.

Models and routing

This token has no access to model xxx

The key has model limits configured and the model you called is not on the allowed list. Edit the key to add it, or clear the restriction.

This token has no access to any model

The model-limit configuration is effectively empty. Edit the key to reselect models, or clear the restriction.

Model name is required

The request body is missing the model field, or the field name is misspelled.

No available channel for model yyy in group xxx

The model you requested has no available capacity on the current supplier route. Causes and fixes:

1. Misspelled model name — the most common. Copy the exact name from the model catalog, watching case, hyphens and version suffixes.
2. That route does not serve this model — switch supplier, or set the key's routing to Smart routing → Smart automatic and let the system find a route that does.
3. The model is genuinely unavailable right now — retry later; if it persists, contact support.

No access to this group

Your account is not entitled to that supplier route. Use one of the suppliers offered by default on your key; if you genuinely need a specific route, contact support.

Upstream for this group is saturated, please retry later

The route's queue is full. Retry shortly, or switch to smart routing so the system moves to another available route.

Platform-side rate limiting

You have reached the request limit: at most M requests in N minutes

Reduce concurrency and add exponential backoff.

There is also a total request limit that counts failed requests too. Code that retries failures rapidly can burn through it, making recovery slower rather than faster. Always back off — never retry immediately.

Invalid request, ...

The platform rejected the request before forwarding it (as opposed to an upstream invalid_request_error). Check Content-Type, JSON syntax and required fields — see Invalid request parameters.

Results not as expected

Calls succeed but cost more than expected

See Usage & Logs → Investigating cost. The most frequent cause is input tokens far above expectations — long context, whole documents in prompts, accumulated conversation history.

Generated image URLs do not open

Raw upstream image URLs typically expire quickly. Store results yourself, or see Bring Your Own Storage to archive them automatically.

Responses are slow

• Check the duration and retry count for that request in Usage Logs. Many retries indicate an unstable upstream.
• Try switching the key's routing strategy to speed first.
• Long outputs are inherently slow; streaming (stream: true) improves perceived latency substantially.

Still stuck

Contact site support with:

1. the Request ID (expand the failed entry in usage logs);
2. roughly when the error occurred;
3. the verbatim error message;
4. which key was used (the name is enough — never send the key itself).