错误码参考
本文档列出了 UPath API 可能返回的所有错误码及其处理建议。
通用错误码
适用于所有 API 接口的通用错误。
| 错误码 |
HTTP 状态码 |
说明 |
处理建议 |
| InvalidParameter |
400 |
请求参数无效 |
检查请求参数格式和必填项 |
| Unauthorized |
401 |
认证失败 |
检查 Token 或 API Key 是否有效 |
| Forbidden |
403 |
无权限访问 |
检查账户状态或权限设置 |
| NotFound |
404 |
资源不存在 |
检查请求的资源 ID 是否正确 |
| InternalError |
500 |
服务器内部错误 |
稍后重试，如持续出现请联系支持 |
认证相关错误
JWT Token 错误
| 错误码 |
HTTP 状态码 |
说明 |
处理建议 |
| TokenExpired |
401 |
Token 已过期 |
使用 Refresh Token 刷新 |
| TokenInvalid |
401 |
Token 无效 |
重新登录获取新 Token |
| TokenMissing |
401 |
未提供 Token |
在请求头添加 Authorization |
API Key 错误
| 错误码 |
HTTP 状态码 |
说明 |
处理建议 |
| ApiKeyInvalid |
401 |
API Key 无效 |
检查 Key 是否正确 |
| ApiKeyExpired |
401 |
API Key 已过期 |
创建新的 API Key |
| ApiKeyDisabled |
401 |
API Key 已禁用 |
联系管理员启用或创建新 Key |
AIGC 接口错误
getScenes 错误
| 错误码 |
HTTP 状态码 |
说明 |
处理建议 |
| InvalidParameter |
400 |
RoomId 参数不能为空 |
提供有效的 RoomId |
| SceneNotFound |
404 |
指定的场景不存在 |
检查 scene_name 参数 |
StartVoiceChat 错误
| 错误码 |
HTTP 状态码 |
说明 |
处理建议 |
| InvalidParameter |
400 |
必填参数缺失 |
检查 SceneID 和 RoomId |
| INSUFFICIENT_BALANCE |
403 |
账户余额不足 |
充值后重试 |
| PRICING_CONFIG_NOT_FOUND |
404 |
场景计费配置不存在 |
联系管理员配置 |
| RTC_SERVICE_ERROR |
500 |
RTC 服务异常 |
稍后重试 |
StopVoiceChat 错误
| 错误码 |
HTTP 状态码 |
说明 |
处理建议 |
| InvalidParameter |
400 |
RoomId 参数不能为空 |
提供有效的 RoomId |
| RoomNotFound |
404 |
房间不存在或已结束 |
检查 RoomId 是否正确 |
用户接口错误
注册错误
| 错误码 |
HTTP 状态码 |
说明 |
处理建议 |
| UsernameExists |
400 |
用户名已存在 |
更换用户名 |
| PhoneExists |
400 |
手机号已注册 |
使用该手机号登录 |
| EmailExists |
400 |
邮箱已注册 |
更换邮箱 |
| SmsCodeInvalid |
400 |
验证码错误或已失效 |
重新获取验证码 |
登录错误
| 错误码 |
HTTP 状态码 |
说明 |
处理建议 |
| AccountNotFound |
400 |
账号不存在 |
检查用户名/手机号/邮箱 |
| PasswordWrong |
400 |
密码错误 |
检查密码或重置密码 |
| AccountDisabled |
400 |
账户已禁用 |
联系管理员 |
| SmsCodeInvalid |
400 |
验证码错误或已失效 |
重新获取验证码 |
错误响应格式
所有错误响应遵循统一格式：
| 字段 |
类型 |
说明 |
| success |
boolean |
固定为 false |
| message |
string |
错误描述 |
| code |
string |
错误码 |
| errors |
object |
详细错误信息（可选） |
错误处理建议
重试策略
对于以下错误，建议实现自动重试：
| 错误类型 |
建议策略 |
| 5xx 错误 |
指数退避重试，最多 3 次 |
| 网络超时 |
等待 1-3 秒后重试 |
| TokenExpired |
自动刷新 Token 后重试 |
不建议重试的错误
| 错误类型 |
原因 |
| 400 参数错误 |
需要修正请求参数 |
| 401 认证错误 |
需要重新认证 |
| 403 余额不足 |
需要充值 |
| 404 资源不存在 |
需要检查资源 ID |
频率限制
过于频繁的重试可能触发频率限制，建议在重试间隔中加入适当延迟。