错误响应格式
所有错误响应遵循统一格式:标准错误响应格式
字段说明:
error: 错误类型(对应 HTTP 状态码)message: 人类可读的错误描述details: 可选的额外错误信息statusCode: HTTP 状态码correlationId: 用于追踪请求的唯一标识符(注意:401 认证错误不包含此字段)X-Correlation-Id响应头:与响应体中的correlationId相同(注意:401 错误也不包含此响应头)
HTTP 状态码
| 状态码 | 类型 | 说明 |
|---|---|---|
| 400 | BadRequest | 请求参数错误 |
| 401 | Unauthorized | 认证失败 |
| 403 | Forbidden | 权限不足 |
| 404 | NotFound | 资源不存在 |
| 409 | Conflict | 资源冲突 |
| 429 | TooManyRequests | 超过速率限制(⚠️ 当前未实现限流功能) |
| 500 | InternalServerError | 服务器内部错误 |
| 503 | ServiceUnavailable | 服务暂时不可用 |
常见错误
错误响应层级说明:
- 401 认证错误:在 middleware 层处理
- 响应体格式:
{error, message, statusCode}(无correlationId和details) - 响应头:不包含
X-Correlation-Id
- 响应体格式:
- 其他错误(400、403、500 等):在 API 路由层处理
- 响应体格式:
{error, message, statusCode, correlationId, details?} - 响应头:包含
X-Correlation-Id
- 响应体格式:
- 429 错误:当前未实现,不会返回此错误(错误类型已定义但未使用)
401 Unauthorized
原因:API Key 无效、缺失或格式错误 认证失败有以下几种情况,错误消息会相应变化:缺少 Authorization 头
缺少 Authorization 头
Authorization 格式错误
Authorization 格式错误
Token 无效或已过期
Token 无效或已过期
401 错误响应
- 检查 API Key 是否正确
- 确认 Authorization 头格式:
Bearer YOUR_API_KEY - 验证 API Key 是否已过期
- 确认外部认证服务是否可用
403 Forbidden
原因:模型或工具不在许可列表中403 错误响应
- 使用
GET /api/v1/models查看可用模型 - 使用
GET /api/v1/tools查看可用工具 - 联系管理员升级权限
400 BadRequest - 缺少必需上下文
原因:工具缺少必需的上下文参数400 错误响应
- 使用
GET /api/v1/tools查看工具的requiredContext - 在
context或toolContext中提供缺失的字段 - 或使用
contextStrategy: "skip"跳过该工具
429 TooManyRequests(当前未实现)
理论响应格式(如果实现):429 错误响应(理论)
设计说明:如果未来实现限流功能,建议通过 HTTP 响应头
Retry-After(单位:秒)传递重试等待时间:- 实现指数退避重试策略
- 读取响应头
Retry-After获取建议的重试时间 - 减少并发请求数
- 联系销售团队提升限额
500 InternalServerError
原因:服务器内部错误500 错误响应
- 使用
correlationId联系技术支持 - 稍后重试
- 检查服务状态页
错误处理最佳实践
1️⃣ 使用 try-catch 包裹请求
1️⃣ 使用 try-catch 包裹请求
基础错误处理
2️⃣ 实现重试机制
2️⃣ 实现重试机制
重试机制实现
关键点:
- ⚠️ 当前 API 未实现 429 限流,上述代码为未来兼容性保留
- 其他错误使用指数退避策略(2^i 秒:1s, 2s, 4s)
- 如果未来实现 429,建议读取
Retry-After响应头
3️⃣ 记录 correlationId
3️⃣ 记录 correlationId
记录 correlationId
correlationId 获取方式:
- 错误响应:从响应体
data.correlationId或响应头X-Correlation-Id获取(两者相同) - 成功响应:只能从响应头
X-Correlation-Id获取(响应体不包含) - 401 错误:两处都不包含,无法获取 correlationId
- 联系技术支持时提供此 ID 可以快速定位问题
4️⃣ 区分错误类型
4️⃣ 区分错误类型
错误类型处理
注意:当前 API 不会返回 429 错误(未实现限流),case 429 为未来兼容性保留。
完整示例
完整示例特点:
- ⚠️ 包含 429 限流处理(当前未实现,为未来兼容性保留)
- ✅ 网络错误等使用指数退避重试(1s, 2s, 4s)
- ✅ 正确获取
correlationId:优先从响应体,失败则从响应头X-Correlation-Id - ✅ 记录
correlationId便于问题追踪 - ✅ 最多重试 3 次后抛出最后一次的错误
- 💡 建议保留 429 处理逻辑,以便 API 未来添加限流时无需修改代码
调试技巧
关于成功响应的 correlationId:成功响应(200 OK)的响应体中不包含
correlationId 字段,但响应头中包含 X-Correlation-Id。建议在所有请求(成功或失败)中记录此响应头,便于追踪完整的请求链路。获取方式:- JavaScript:
response.headers.get('X-Correlation-Id') - Python (requests):
response.headers.get('X-Correlation-Id')
记录 correlationId
保存每个请求的
correlationId(响应体或响应头),便于问题排查使用 validateOnly
在正式调用前验证参数配置
监控错误率
跟踪不同类型错误的发生频率
日志记录
记录完整的请求和响应,便于复现问题

