错误处理

所有 API 接口统一使用一套错误响应模型。
当请求失败时，请优先根据 HTTP 状态码和错误信息定位原因。

通用状态码

状态码	含义	常见原因
400 Bad Request	请求参数错误	必填字段缺失、格式不合法、资源输入无效
401 Unauthorized	认证失败	Bearer Token / API Key 缺失、过期或无效
403 Forbidden	权限不足	当前凭证不具备所需权限范围
413 Payload Too Large	请求体过大	文件或远程资源超过系统大小限制
422 Unprocessable Entity	校验失败	Body/Query/Path 参数未通过校验
429 Too Many Requests	触发频控或配额限制	请求频率过高或调用量超出额度
500 Internal Server Error	服务内部错误	服务端发生未预期异常
502 Bad Gateway	上游服务异常	模型或存储等上游返回异常响应
503 Service Unavailable	服务暂时不可用	后端依赖暂时不可用或负载过高

排查建议

• 先检查请求体类型和必填字段是否完整。
• 确认 Authorization 头是否正确且未过期。
• 遇到 429 建议指数退避重试，并核对配额策略。
• 遇到 5xx 可稍后重试；若持续出现，请带上请求信息联系支持。