Errors, limits, and retries
Diagnose HTTP errors and distinguish allowance limits from rate limits.
Diagnose HTTP errors and distinguish allowance limits from rate limits.
Record time and timezone, HTTP status, model ID, protocol, client version, and sanitized error details. Keep any request identifier returned. Do not send complete authentication headers to support.
Reproduce with the basic request, then add options individually. Console and model endpoints use different error formats; a single fixed error.code is not universal.
Status or symptom | Check and action |
|---|---|
400 | JSON, required fields, parameters, context and output limits; correct before retrying |
401 | Complete key, inherited environment variables, and protocol authentication header |
403 | Key or member status, model permissions, source allowlists, or allowance issues described by the error |
404 | Host, version prefix, operation, model, and duplicate |
413 | Oversized payload or file; resize or split according to model limits |
429 | Distinguish rate, concurrency, and allowance limits; follow the response |
5xx | Temporary gateway or model-service failure; preserve details and retry carefully or contact support |
Timeout or interrupted stream | Network, proxies, client timeout, and stream events; determine whether execution occurred |
These are diagnostic directions, not a shared error-code contract for every model service. Balance and permission errors can use different statuses and messages.
Balance, subscription allowances, member budgets, key status, model access, request frequency, and concurrency are separate controls. Adding funds may not fix rate limits, and waiting cannot restore an exhausted budget. Actual limits depend on the account and line configuration.
For recoverable 429 or temporary server errors, use bounded exponential backoff with jitter and honor Retry-After when provided. Configuration or permission failures such as 400, 401, and 403 usually require correction before retrying.
Avoid stacking aggressive SDK, application, and queue retries. A timeout can occur after execution; check task status or use business deduplication, especially for images, video, and tool side effects. Retrying after partial streamed output starts a new generation and may incur additional usage.
For persistent failures, use the support template.