Errors and retries
Retry temporary failures and correct request errors before sending again.
When a call fails, save the HTTP status, redacted error body, request time, endpoint, Model ID, and any available request identifier before deciding whether to retry.
Common errors
| Result | Check first | Retry immediately? |
|---|---|---|
400 invalid request | JSON, Model ID, field types, and model support | No; correct the request |
401 authentication failed | API key, Bearer format, and credential status | No; correct the credential |
403 access restricted | Account, model scope, region, or source restrictions | No; confirm access |
404 path or resource missing | API address, endpoint, Model ID, or task identifier | No; review configuration |
429 too many requests | Request rate, concurrency, and returned rate-limit guidance | Retry a limited number of times at a lower rate |
5xx service error | Request ID and whether the original request ran | Retry a limited number of times based on the error |
| Timeout or connection interruption | Network, client timeout, and request status | Do not retry blindly |
| Insufficient balance or budget | Available balance, key budget, and cost protection | Resolve the restriction first |
Use the actual API response as the source of truth for error bodies and status codes.
Configure retries
Retry only errors that may recover, and set limits for attempts and total wait time. Follow explicit retry guidance in the response when available.
Example: retry up to 3 times, wait about 1, 2, and 4 seconds, and add a small random delay.This is an application strategy example. It does not guarantee that a platform limit will end at those times. Do not enable unlimited retries in the SDK, application, and gateway at the same time.
Avoid duplicate requests
After a client timeout, check the original request in Requests. For image generation or long-running tasks, check an existing request or task identifier before submitting again. Use an idempotency field or header only when the interface explicitly supports it.
Contact support
Provide the Request ID, request time and time zone, Model ID, endpoint, HTTP status, redacted error, and troubleshooting steps already completed. Never send a password, verification code, complete API key, or unrelated sensitive content.