HTTP 状态码
本文档说明 UPath API 使用的 HTTP 状态码及其含义。
成功状态码
| 状态码 |
含义 |
使用场景 |
| 200 OK |
请求成功 |
查询、更新操作成功 |
| 201 Created |
创建成功 |
注册、创建资源成功 |
| 204 No Content |
删除成功 |
删除资源成功，无响应体 |
客户端错误状态码
| 状态码 |
含义 |
常见原因 |
| 400 Bad Request |
请求错误 |
参数格式错误、必填参数缺失 |
| 401 Unauthorized |
未授权 |
Token/API Key 无效或过期 |
| 403 Forbidden |
禁止访问 |
无权限、余额不足、账户禁用 |
| 404 Not Found |
资源不存在 |
请求的资源 ID 不存在 |
| 405 Method Not Allowed |
方法不允许 |
使用了不支持的 HTTP 方法 |
| 429 Too Many Requests |
请求过多 |
触发频率限制 |
服务端错误状态码
| 状态码 |
含义 |
处理建议 |
| 500 Internal Server Error |
服务器内部错误 |
稍后重试 |
| 502 Bad Gateway |
网关错误 |
稍后重试 |
| 503 Service Unavailable |
服务不可用 |
服务维护中，稍后重试 |
| 504 Gateway Timeout |
网关超时 |
网络问题，稍后重试 |
状态码与接口对应关系
用户接口
| 接口 |
成功状态码 |
可能的错误状态码 |
| 发送验证码 |
200 |
400, 429 |
| 用户注册 |
201 |
400 |
| 用户登录 |
200 |
400, 401 |
API 密钥接口
| 接口 |
成功状态码 |
可能的错误状态码 |
| 获取密钥列表 |
200 |
401 |
| 创建密钥 |
201 |
400, 401 |
| 获取密钥详情 |
200 |
401, 404 |
| 删除密钥 |
204 |
401, 404 |
AIGC 接口
| 接口 |
成功状态码 |
可能的错误状态码 |
| getScenes |
200 |
400, 401, 404 |
| StartVoiceChat |
200 |
400, 401, 403, 404, 500 |
| StopVoiceChat |
200 |
400, 401, 404 |
控制台接口
| 接口 |
成功状态码 |
可能的错误状态码 |
| 控制台概览 |
200 |
401 |
| 用量趋势 |
200 |
400, 401 |
| API 统计 |
200 |
400, 401 |
处理建议
4xx 错误处理
400 → 检查请求参数
401 → 刷新 Token 或检查 API Key
403 → 检查账户状态和余额
404 → 检查资源 ID
429 → 降低请求频率
5xx 错误处理
5xx → 实现指数退避重试策略
→ 第 1 次重试：等待 1 秒
→ 第 2 次重试：等待 2 秒
→ 第 3 次重试：等待 4 秒
→ 超过 3 次后放弃并报警
监控建议
建议对 4xx 和 5xx 错误率进行监控，异常时及时告警。