Guide HTTP Status Codes
When calling API you will see standard HTTP status codes in addition to business JSON fields such as `success` / `code`. Common meanings and what to do:
When calling API you will see standard HTTP status codes in addition to business JSON fields such as success / code. Common meanings and what to do:
2xx Success
| Code | Meaning | Notes |
|---|
| 200 | OK | Success. Async submit often returns 200 too — you still need to poll the task |
| 201 | Created | Resource created (uncommon; follow the specific API doc) |
4xx Client errors
| Code | Meaning | Typical cause | Action |
|---|
| 400 | Bad Request | Missing/invalid params, bad JSON | Check body / query against the OpenAPI |
| 401 | Unauthorized | Bad/expired key, missing Authorization | Verify Bearer sk-... and token status |
| 403 | Forbidden | No permission, model/group limits, IP deny | Check model limits, group, allow_ips |
| 404 | Not Found | Wrong path, missing task/resource | Check Base URL + path; confirm task_id |
| 408 | Timeout | Client or gateway timeout | Shrink payload, retry, or use async APIs |
| 429 | Too Many Requests | Rate limited | Back off; lower concurrency |
5xx Server / upstream
| Code | Meaning | Action |
|---|
| 500 | Internal Server Error | Retry later; if persistent, report with request_id / task id |
| 502 / 503 / 504 | Bad gateway / unavailable / timeout | Exponential backoff; reduce concurrency at peak |
Troubleshooting tips
- If the body starts with
< (HTML), the Base URL or path is usually wrong. - Some business errors still return HTTP 200 with the error in JSON
message / error — follow each platform OpenAPI. - Async: submit success ≠ generation success. See Async Task Guide.
