Skip to main content
Read the response status and error.message first. Then open logs in the console for the key’s workspace and select the failed request.

​
Find the fix

The table describes common model-request errors. Billing and credential-management endpoints may return their own error types; consult the API Reference for the endpoint you called.

​
Retries and rate limits

The gateway does not publish a fixed per-key request or token allowance. Upstream provider capacity still applies. On text endpoints, a provider rate-limit failure can surface as 502 upstream_error; the request log records status: "rate_limited". Do not treat every 502 as a temporary rate limit.
  • Retry temporary capacity, network, and availability failures with exponential backoff and jitter.
  • Limit concurrent requests and total attempts. The gateway already performs routing retries and failover, and your SDK may retry too.
  • Do not automatically retry invalid input, invalid credentials, or insufficient balance without changing the cause.
  • A timeout does not prove that the provider did no work. Treat a retry as a new request, and prevent duplicate application actions.

​
A stream started, then failed

HTTP 200 means the stream opened, not that generation completed. After content begins, the gateway cannot silently restart on another route. Check for protocol error events and the expected completion event, and show an incomplete response if the stream ends early. Follow the SDK’s streaming error handling. If you parse raw SSE, handle fragmented frames and errors instead of only collecting text. See streaming.
Messages uses Anthropic’s envelope, for example:
Messages uses not_found_error for an unknown model and api_error for provider failures. max_tokens is required. Gemini-native errors use Google’s status envelope. Parse errors according to the endpoint you call rather than assuming every format has the OpenAI error shape.
Check that the deployed server has the same key and base URL as your terminal. OpenAI SDKs need /v1 in the base URL; Anthropic SDKs need the gateway root. Model calls belong on your server, not directly in browser code.Check proxy timeouts and buffering for streams. If the request reaches the gateway, inspect its log for the model, status, provider, and error message. Authentication failures can occur before a request log is created.
Include the UTC time, endpoint, model ID, HTTP status, error message, and request log ID. If you set x-request-id, include that value too. Provide a small example with credentials and sensitive prompt content removed.The log row’s id is used with GET /v1/requests/{id}; its requestId is a separate correlation field. Never share the API key or provider credential.
For unsupported features and endpoint limits, see API compatibility. Fast and Ultrafast requests return 400 for unsupported models or incompatible deployment pins. Anthropic Fast rate limits (429) and capacity errors (529) use the upstream mapping above; the gateway never downgrades speed automatically. See speed tiers for an explicit client fallback.