错误码参考¶
📖 概述¶
agtcloud 系统提供完整的错误码体系，帮助开发者快速定位和解决问题。错误码分为三大类：
- 上游状态码：来自上游服务提供商（如 OpenAI、Anthropic 等）的错误码和状态信息
- 任务状态码：异步任务处理过程中的状态码（如 Midjourney 图像生成）
- 内部错误码：New API 内部系统在请求处理各阶段产生的错误码
上游状态码¶
错误码列表¶
| HTTP 状态码 | 错误类型 | 透传级别 | 中文描述 | 英文描述 | 典型上游错误码 | 典型上游消息 | New API 处理方式 | 客户端接收示例 |
|---|---|---|---|---|---|---|---|---|
| 401 | upstream_error | 完全透传 | 上游鉴权失败 | Upstream authentication failed | invalid_api_key / invalid_request_error |
Incorrect API key provided | 保持 401 状态码并透传上游 error 对象 | HTTP 401 + {"error":{"message":"<上游原文>","type":"upstream_error","code":"<上游 code>"}} |
| 403 | upstream_error | 完全透传 | 上游权限不足或账号被封 | Upstream forbidden / account banned | account_deactivated / model_not_available |
Your account has been deactivated | 保持 403 状态码并透传上游 error 对象 | HTTP 403 + {"error":{"message":"<上游原文>","type":"upstream_error","code":"<上游 code>"}} |
| 404 | upstream_error | 完全透传 | 上游资源不存在 | Upstream resource not found | model_not_found / DeploymentNotFound |
The model does not exist | 保持 404 状态码并透传上游 error 对象 | HTTP 404 + {"error":{"message":"<上游原文>","type":"upstream_error","code":"<上游 code>"}} |
| 429 | upstream_error | 完全透传 | 上游速率限制或配额耗尽 | Upstream rate limit / quota exceeded | rate_limit_exceeded / insufficient_quota |
Rate limit reached | 保持 429 状态码并透传上游 error 对象（可能触发自动重试） | HTTP 429 + {"error":{"message":"<上游原文>","type":"upstream_error","code":"<上游 code>"}} |
| 500 | upstream_error | 完全透传 | 上游内部服务器错误 | Upstream internal server error | internal_error / server_error |
The server had an error processing your request | 保持 500 状态码并透传上游 error 对象 | HTTP 500 + {"error":{"message":"<上游原文>","type":"upstream_error","code":"<上游 code>"}} |
| 502 | upstream_error | 完全透传 | 上游网关错误 | Upstream bad gateway | bad_gateway |
Bad gateway | 保持 502 状态码并透传上游 error 对象 | HTTP 502 + {"error":{"message":"<上游原文>","type":"upstream_error","code":"<上游 code>"}} |
| 503 | upstream_error | 完全透传 | 上游服务不可用 | Upstream service unavailable | service_unavailable / overloaded |
The engine is currently overloaded | 保持 503 状态码并透传上游 error 对象（可能触发渠道降级） | HTTP 503 + {"error":{"message":"<上游原文>","type":"upstream_error","code":"<上游 code>"}} |
| 504 | upstream_error | 完全透传 | 上游网关超时 | Upstream gateway timeout | timeout |
Your request timed out | 保持 504 状态码并透传上游 error 对象 | HTTP 504 + {"error":{"message":"<上游原文>","type":"upstream_error","code":"<上游 code>"}} |
| 非标准格式 | upstream_error | 部分透传 | 上游返回非 OpenAI 标准格式 | Upstream non-standard error format | N/A | 各种非标准格式（纯文本、HTML、非标准 JSON） | 提取 message 字段并包装为 bad_response_status_code | HTTP <原状态码> + {"error":{"message":"bad response status code <code>, message: <提取的文本>","type":"new_api_error","code":"bad_response_status_code"}} |
任务状态码¶
错误码列表¶
| 错误码 | 错误类型 | HTTP 状态码 | 系统 | 中文描述 | 英文描述 | 触发条件 | 客户端接收示例 |
|---|---|---|---|---|---|---|---|
| 1 | midjourney_success | 200 | Midjourney | 任务提交成功 | Task submitted successfully | MJ 代理成功接收并排队任务 | {"code":1,"description":"提交成功","result":"<task_id>"} |
| 4 | midjourney_error | 400 | Midjourney | 请求参数错误 | Invalid request parameters | 缺少必填参数（如 prompt）或参数格式错误 | {"code":4,"description":"<错误详情>"} |
| 21 | midjourney_info | 200 | Midjourney | 任务已存在 | Task already exists | 重复提交相同的任务（已在处理或已完成） | {"code":21,"description":"任务已存在","result":"<task_id>"} |
| 22 | midjourney_info | 200 | Midjourney | 任务排队中 | Task queued | 任务已提交但前面还有其他任务在排队 | {"code":22,"description":"排队中，前面还有 N 个任务"} |
| 23 | midjourney_error | 429 | Midjourney | 队列已满 | Queue is full | MJ 代理的任务队列已达到上限 | {"code":23,"description":"队列已满，请稍后尝试"} |
| 24 | midjourney_error | 400 | Midjourney | Prompt 包含敏感词 | Prompt contains banned words | Prompt 触发了 Midjourney 的内容过滤 | {"code":24,"description":"可能包含敏感词"} |
| 3 | midjourney_error | 403 | Midjourney | 无可用账号实例 | No available account | MJ 代理后端无可用的 Discord 账号 | {"code":3,"description":"No available account instance"} |
| 30 | midjourney_error | 429 | Midjourney | 分组负载饱和 | Group load saturated | 当前分组的并发请求数已达到上限 | {"code":30,"description":"当前分组负载已饱和"} |
| task_not_exist | task_error | 404 | Task System | 任务不存在 | Task not found | 查询的 task_id 在数据库中不存在或不属于当前用户 | {"code":"task_not_exist","message":"查询的任务 ID 不存在"} |
| quota_not_enough | task_error | 403 | Task System | 任务额度不足 | Insufficient quota for task | 提交任务时用户余额不足以支付预估费用 | {"code":"quota_not_enough","message":"任务额度计算失败或余额不足"} |
| invalid_api_platform | task_error | 400 | Task System | 无效的平台参数 | Invalid platform parameter | 请求的平台类型不受支持（如拼写错误） | {"code":"invalid_api_platform","message":"invalid api platform: <platform>"} |
| fail_to_fetch_task | task_error | 上游状态码 | Task System | 获取任务失败 | Failed to fetch task from upstream | 向上游查询任务状态时上游返回错误 | {"code":"fail_to_fetch_task","message":"<上游错误详情>"} |
内部错误码¶
New API 内部系统在请求处理各阶段产生的错误码。
错误码列表¶
| 错误码 | 错误类型 | HTTP 状态码 | 触发阶段 | 中文描述 | 英文描述 | 典型原因 | 建议操作 |
|---|---|---|---|---|---|---|---|
| invalid_request | new_api_error | 400 | 请求解析阶段 | 无效的请求格式或参数 | Invalid request format or parameters | 请求体 JSON 格式错误、必填字段缺失、模型名为空 | 检查请求格式是否符合 OpenAI 规范 |
| sensitive_words_detected | new_api_error | 400 | 内容审核阶段 | 请求内容包含敏感词 | Sensitive words detected | Prompt 触发了系统配置的敏感词库 | 修改 Prompt 内容或联系管理员调整敏感词库 |
| insufficient_user_quota | new_api_error | 403 | 预扣费阶段 | 用户额度不足 | Insufficient user quota | 账户余额为 0 或低于本次请求预估消耗 | 充值或联系管理员增加额度 |
| pre_consume_token_quota_failed | new_api_error | 403 | 预扣费阶段 | 预扣费失败 | Pre-consume quota failed | 令牌剩余额度不足或已达到使用上限 | 检查令牌配额或使用其他令牌 |
| get_channel_failed | new_api_error | 500 | 渠道选择阶段 | 无可用渠道 | No available channel | 所有渠道已禁用、模型未配置到任何渠道、或渠道全部离线 | 检查渠道状态和模型映射配置 |
| count_token_failed | new_api_error | 500 | Token 计算阶段 | Token 数量计算失败 | Token count failed | Tokenizer 库异常或请求内容格式异常 | 联系技术支持排查 |
| model_price_error | new_api_error | 500 | 定价查询阶段 | 模型定价信息缺失 | Model pricing not configured | 该模型未在后台配置价格 | 在后台"模型价格"中添加该模型的定价 |
| read_request_body_failed | new_api_error | 400 | 请求读取阶段 | 读取请求体失败 | Failed to read request body | 请求体过大（超过限制）或连接中断 | 减小请求体大小或检查网络连接 |
| access_denied | new_api_error | 403 | 鉴权阶段 | 拒绝访问 | Access denied | IP 不在白名单、令牌已失效、或用户被封禁 | 检查 IP 白名单配置或令牌有效性 |
| model_not_found | new_api_error | 404 | 模型查找阶段 | 模型未找到 | Model not found | 请求的模型在当前可用渠道中不存在 | 检查模型名拼写或添加支持该模型的渠道 |
| prompt_blocked | new_api_error | 400 | 内容过滤阶段 | 提示词被拦截 | Prompt blocked by filter | 触发了 OpenAI 内容策略或自定义过滤规则 | 修改 Prompt 避免违规内容 |
| convert_request_failed | new_api_error | 500 | 请求转换阶段 | 请求格式转换失败 | Request conversion failed | 该渠道类型不支持此 API 端点或参数不兼容 | 检查端点和渠道类型的兼容性 |
| channel:no_available_key | channel_error | 500 | 渠道 Key 选择阶段 | 渠道无可用 Key | No available key | 该渠道的所有 API Key 都已失效或达到并发上限 | 更换或添加新的 API Key |
| channel:invalid_key | channel_error | 401 | 渠道 Key 验证阶段 | 渠道 Key 无效 | Invalid channel key | 渠道配置的 API Key 已过期或被上游撤销 | 更新渠道的 API Key |
| channel:response_time_exceeded | channel_error | 504 | 请求超时阶段 | 渠道响应超时 | Channel response timeout | 上游响应时间超过系统设置的超时阈值 | 增加超时时间或检查上游服务状态 |
| do_request_failed | new_api_error | 500 | HTTP 请求阶段 | 请求上游失败 | Failed to send request to upstream | 网络连接失败、DNS 解析失败、或上游服务器拒绝连接 | 检查网络连接和上游服务器状态 |
| api_not_implemented | new_api_error | 501 | 路由匹配阶段 | API 端点未实现 | API endpoint not implemented | 该端点在当前版本中尚未实现 | 等待版本更新或使用其他端点 |