错误码说明
AI 服务平台（AISP）通过标准 HTTP 状态码和业务错误码相结合的方式返回错误信息。 本文档详细列出了所有可能遇到的错误码及其含义，帮助开发者快速定位和解决问题。
错误响应格式
所有接口错误均返回统一的 JSON 格式：
// 成功响应
{
"code": 200,
"msg": "success",
"data": { ... }
}
// 错误响应
{
"code": 400,
"msg": "错误描述信息",
"data": null
}HTTP 状态码
接口使用标准 HTTP 状态码表示请求的处理结果：
| HTTP 状态码 | 含义 | 说明 |
|---|---|---|
| 200 | 请求成功 | 接口正常返回，具体数据见响应体 |
| 400 | 请求参数错误 | 请求参数缺失、格式不正确或不符合预期 |
| 401 | 未授权 | API Key 缺失、无效或已过期 |
| 403 | 禁止访问 | 余额不足、无权限访问该资源 |
| 404 | 资源不存在 | 请求的模型、任务或接口地址不存在 |
| 429 | 请求过于频繁 | 触发了限流策略，请稍后重试 |
| 500 | 服务端错误 | 平台内部错误或第三方服务异常 |
| 502 | 网关错误 | 上游模型服务暂时不可用 |
| 503 | 服务不可用 | 平台维护中或所有模型服务均不可用 |
| 504 | 网关超时 | 上游模型服务响应超时 |
业务错误码详解
以下为平台返回的常见业务错误场景及解决方案：
400 - 参数错误
| 错误信息 | 触发场景 | 解决方案 |
|---|---|---|
| Parameter error: model is required | 请求缺少 model 参数 | 检查请求体，确保传入 model 字段 |
| Parameter error: messages is required | Chat 接口缺少 messages 参数 | 传入 messages 数组 |
| Parameter error: text is required | TTS 接口缺少 text 参数 | 传入需要转换的文本内容 |
| Invalid parameter format | 参数类型不正确 | 检查参数类型是否符合文档要求 |
| Text exceeds maximum length | TTS 文本超过 5000 字符 | 缩短文本内容或分批调用 |
| Invalid size format | 图片尺寸格式不正确 | 使用标准格式如 1024*1024 |
401 - API Key 无效
| 错误信息 | 触发场景 | 解决方案 |
|---|---|---|
| Authorization header is required | 请求未携带 Authorization 头 | 添加 Authorization: Bearer sk-xxxx |
| Invalid API Key | API Key 不存在或格式错误 | 检查 API Key 是否正确，重新创建 Key |
| API Key has been deleted | API Key 已被删除 | 创建新的 API Key 并替换 |
| API Key has been expired | API Key 已过期 | 在控制台续期或创建新 Key |
403 - 余额不足 / 权限受限
| 错误信息 | 触发场景 | 解决方案 |
|---|---|---|
| Insufficient balance | 账户余额不足以支付本次调用费用 | 充值账户余额后重试 |
| No permission for this model | 当前 Key 没有该模型的访问权限 | 在控制台为 Key 开通对应模型权限 |
| Account has been banned | 账户因违规被封禁 | 联系客服申诉 |
| Rate limit exceeded | 请求频率超过限制 | 降低请求频率或申请更高限额 |
404 - 资源不存在
| 错误信息 | 触发场景 | 解决方案 |
|---|---|---|
| Model not found: xxx | 传入了不存在的模型名称 | 查看支持的模型列表，使用正确的模型名 |
| Task not found: xxx | 查询的任务 ID 不存在 | 检查任务 ID 是否正确 |
| API endpoint not found | 请求的接口地址不存在 | 检查接口 URL 是否正确 |
500 - 服务端错误
| 错误信息 | 触发场景 | 解决方案 |
|---|---|---|
| Internal server error | 平台内部异常 | 稍后重试或联系客服 |
| Model service unavailable | 上游模型服务不可用 | 切换其他模型或稍后重试 |
| Model response timeout | 模型响应超时 | 稍后重试或使用更快的模型 |
| Audio generation failed | 音频合成失败 | 检查输入文本或切换音色 |
| Image generation failed | 图片生成失败 | 修改 prompt 或重试 |
| Video generation failed | 视频生成失败 | 修改 prompt 或重试 |
错误响应示例
以下为各种错误场景的完整响应示例：
// 400 参数错误
{ "code": 400, "msg": "Parameter error: model is required" }
// 401 API Key 无效
{ "code": 401, "msg": "Invalid API Key" }
// 403 余额不足
{ "code": 403, "msg": "Insufficient balance" }
// 403 权限不足
{ "code": 403, "msg": "No permission for this model" }
// 404 模型不存在
{ "code": 404, "msg": "Model not found: xxx-model" }
// 429 请求过于频繁
{ "code": 429, "msg": "Rate limit exceeded, please try again later" }
// 500 服务端错误
{ "code": 500, "msg": "Internal server error" }
// 502 上游服务不可用
{ "code": 502, "msg": "Model service temporarily unavailable" }错误处理建议
客户端处理建议
- 4xx 错误：客户端错误，应在请求前检查参数和鉴权信息，通过代码逻辑修复
- 429 错误：实现指数退避重试策略，避免无限重试
- 5xx 错误：服务端问题，建议重试 2~3 次，间隔 1 秒以上
- 504 错误：模型超时，可尝试切换更快的模型或减少输入长度
- 记录 Request ID：每次请求记录返回的 Request ID，出现问题时便于排查
- 监控告警：建议对 4xx/5xx 错误率设置监控告警
联系技术支持
如遇到无法自行解决的错误，请提供以下信息联系技术支持：
- 错误的完整响应内容（code + msg）
- 请求的接口地址和请求参数
- 请求时间
- API Key（部分脱敏即可）
- 错误的 Request ID（如有）
提供完整的错误信息可以帮助技术支持团队更快定位和解决问题。