Troubleshooting
Find the next step.
Start with the HTTP status and error code. Never include your API key in a support message.
Where to find the error
Most failed API requests return an error object. Keep its code and request_id, or the x-request-id response header.
{
"error": {
"type": "invalid_request_error",
"code": "model_not_found",
"message": "The requested model is not available.",
"request_id": "REQUEST_ID_FROM_RESPONSE"
}
}Common API errors
| Status | Code | What to do |
|---|---|---|
| 401 | missing_api_key, invalid_api_key | Check the Bearer header, extra spaces and which key the client sends. If the secret is lost or revoked, create a new named key in API; existing secrets cannot be shown again. |
| 401 / 403 | supergpt_sign_in_required, key_inactive | Use a key created in API for external apps. A desktop sign-in is not a portable API key. A revoked key cannot be restored; replace it in the client. |
| 403 / 404 | model_not_allowed, model_not_found | Fetch /models with the same key and choose an exact returned ID. Remove a stale or invented model ID. The dashboard does not provide per-key model overrides. |
| 400 | invalid_json, invalid_request, unsupported_parameter | Correct the field named in error.param. Confirm that the client uses Chat Completions or Responses with the corresponding body. Do not retry the same invalid body. |
| 400 | invalid_reasoning_effort, reasoning_effort_conflict | Use an effort supported by the selected model. If the model ID already has an effort suffix, remove the conflicting setting or make it match. |
| 404 | route_not_found | Use the configured base URL with /v1 exactly once. Check whether the client asks for a base URL or a full endpoint. Other API protocols require a compatible client. |
| 402 | balance_required | Check the paid API Wallet in API. Add funds when available. Subscription quota and trial credit do not fund Wallet keys. |
| 402 | quota_insufficient_for_request | Check the relevant weekly or five-hour allowance in Usage. Wait for the displayed reset, reduce the request size, or review available additional quota in Account. |
| 402 | access_expired, subscription_inactive, key_spend_cap_reached | Check the access and limit shown for the key or subscription. Restore the applicable access in Account, or contact support if the displayed state is unexpected. |
| 423 | account_held, keys_frozen | Contact support with the request ID. Repeated retries, a new key or another payment may not resolve an account restriction. |
| 429 | rpm_limit_reached, distributed_rpm_limit_reached, tpm_limit_reached | Follow Retry-After, space requests apart and reduce the amount of text sent at once. A rate limit is not necessarily an empty balance. |
| 429 | active_stream_key_limit_reached, active_stream_account_limit_reached, concurrency_limit_reached, upstream_at_capacity | Wait for active requests to finish and reduce parallel jobs. Honor Retry-After. Do not run repeated connection tests or recreate keys. |
| 426 | responses_websocket_unavailable | Choose HTTP/SSE transport for Responses in your client. This endpoint does not offer WebSocket transport. |
| 413 | payload_too_large | Shorten the conversation or reduce request/attachment size. Do not resend the same oversized body. |
| 502 / 503 / 504 | upstream_error, upstream_unavailable, upstream_empty_response, upstream_timeout | Wait, then try one short request. If the issue persists, contact support with the request ID and time. Check for partial output before repeating a task. |
| 503 | customer_usage_unavailable, subscription_epoch_unavailable | Try again later. If it persists, contact support. Unavailable usage does not mean zero allowance. |
| 500 | internal_error, quota_not_configured | Try again later. If it persists, contact support. Unavailable usage does not mean zero allowance. |
A request may still be running
For idempotency_request_in_progress, wait rather than submitting new copies. idempotency_key_conflict means the same key was used with a different request. Keep an idempotency key for one logical request; do not reuse it for unrelated work.
idempotency_replay_result_unavailable or idempotency_request_terminal does not guarantee that nothing happened. Inspect the client output and Usage before retrying. A fresh attempt can incur additional usage. For invalid_idempotency_key, fix the header format before sending again.
The stream stopped or produced no visible text
A network break, stream_interrupted or response.failed is not a completed answer. Preserve any partial output. Let a reasoning request finish before deciding it is stuck, and check the client’s timeout setting. Repeat only after checking whether tool actions already happened.
Start with a short text task. If text works but editing fails, check the client’s tool configuration and permissions in its setup guide.
Usage is unavailable
Check your connection and refresh the dashboard after a short wait. Do not purchase extra quota just because a percentage cannot load. If a limit has been reached, Usage shows the relevant weekly or five-hour window and reset date.
Compare the exact UTC reset from an API error with the timezone shown by your client. Review available additional capacity in Account only when the dashboard offers it.
Models do not appear in the picker
Confirm that /models works with that client’s key. Some clients require you to add model IDs manually. Add only returned IDs, then reload the client. Do not replace the entire configuration or sign out of unrelated accounts.