HTTP 状态码及其含义
调用API 时，除业务 JSON 内的 success / code 外，还会看到标准 HTTP 状态码。下表为常见含义与处理建议。
2xx 成功
| 状态码 | 含义 | 说明 |
|---|---|---|
| 200 | OK | 请求成功。异步任务提交成功通常也是 200，需再轮询任务状态 |
| 201 | Created | 资源已创建（较少见；以具体接口文档为准） |
4xx 客户端错误
| 状态码 | 含义 | 常见原因 | 建议 |
|---|---|---|---|
| 400 | Bad Request | 参数缺失、类型错误、JSON 无法解析 | 对照接口文档检查 body / query |
| 401 | Unauthorized | API Key 无效、过期、未传 Authorization |
检查 Bearer sk-...；控制台确认令牌状态 |
| 403 | Forbidden | 无权限、分组/模型限制、IP 不在白名单 | 检查令牌模型限制、分组与 allow_ips |
| 404 | Not Found | 路径错误、任务/资源不存在 | 核对 Base URL 与 path；确认 task_id |
| 408 | Timeout | 客户端或网关超时 | 缩短 payload、重试或改异步接口 |
| 429 | Too Many Requests | 触发限流 | 退避重试；降低并发 |
5xx 服务端 / 上游
| 状态码 | 含义 | 建议 |
|---|---|---|
| 500 | Internal Server Error | 稍后重试；若持续出现请带 request_id / 任务 ID 反馈 |
| 502 / 503 / 504 | 网关或上游不可用 / 超时 | 指数退避重试；高峰期可换模型或降并发 |
排错提示
- 若响应体以
<开头（HTML），多半是 Base URL 或路径写错， upstream 返回了网页而非 JSON。 - 业务错误有时仍返回 HTTP 200，错误写在 JSON 的
message/error字段——以各平台 OpenAPI 为准。 - 异步任务：提交成功 ≠ 生成成功，请按异步任务通用说明轮询终态。