Error Code Reference¶
📖 Overview¶
The agtcloud system provides a complete error code system to help developers quickly locate and resolve issues.
Error codes are divided into three main categories:
- Upstream status codes: Error codes and status information returned from upstream providers (e.g. OpenAI, Anthropic)
- Task status codes: Status codes for asynchronous task processing (e.g. Midjourney image generation)
- Internal error codes: Errors generated by the New API system itself at various processing stages
Upstream Status Codes¶
Error Code List¶
| HTTP Status Code | Error Type | Pass-through Level | Description (Chinese) | Description (English) | Typical Upstream Error Code | Typical Upstream Message | New API Handling | Example Client Response |
|---|---|---|---|---|---|---|---|---|
| 401 | upstream_error | full | 上游鉴权失败 | Upstream authentication failed | invalid_api_key / invalid_request_error |
Incorrect API key provided | Keep 401 status and pass upstream error object |
HTTP 401 + {"error":{"message":"<upstream raw message>","type":"upstream_error","code":"<upstream code>"}} |
| 403 | upstream_error | full | 上游权限不足或账号被封 | Upstream forbidden / account banned | account_deactivated / model_not_available |
Your account has been deactivated | Keep 403 status and pass upstream error object |
HTTP 403 + {"error":{"message":"<upstream raw message>","type":"upstream_error","code":"<upstream code>"}} |
| 404 | upstream_error | full | 上游资源不存在 | Upstream resource not found | model_not_found / DeploymentNotFound |
The model does not exist | Keep 404 status and pass upstream error object |
HTTP 404 + {"error":{"message":"<upstream raw message>","type":"upstream_error","code":"<upstream code>"}} |
| 429 | upstream_error | full | 上游速率限制或配额耗尽 | Upstream rate limit / quota exceeded | rate_limit_exceeded / insufficient_quota |
Rate limit reached | Keep 429 status and pass upstream error object (may retry) |
HTTP 429 + {"error":{"message":"<upstream raw message>","type":"upstream_error","code":"<upstream code>"}} |
| 500 | upstream_error | full | 上游内部服务器错误 | Upstream internal server error | internal_error / server_error |
The server had an error processing your request | Keep 500 status and pass upstream error object |
HTTP 500 + {"error":{"message":"<upstream raw message>","type":"upstream_error","code":"<upstream code>"}} |
| 502 | upstream_error | full | 上游网关错误 | Upstream bad gateway | bad_gateway |
Bad gateway | Keep 502 status and pass upstream error object |
HTTP 502 + {"error":{"message":"<upstream raw message>","type":"upstream_error","code":"<upstream code>"}} |
| 503 | upstream_error | full | 上游服务不可用 | Upstream service unavailable | service_unavailable / overloaded |
The engine is currently overloaded | Keep 503 status and pass upstream error object (may degrade) |
HTTP 503 + {"error":{"message":"<upstream raw message>","type":"upstream_error","code":"<upstream code>"}} |
| 504 | upstream_error | full | 上游网关超时 | Upstream gateway timeout | timeout |
Your request timed out | Keep 504 status and pass upstream error object |
HTTP 504 + {"error":{"message":"<upstream raw message>","type":"upstream_error","code":"<upstream code>"}} |
| non-standard | upstream_error | partial | 上游返回非 OpenAI 标准格式 | Upstream non-standard error format | N/A | Various non-standard formats (text/HTML/non-JSON) | Extract message and wrap as bad_response_status_code |
HTTP <status> + {"error":{"message":"bad response status code <code>, message: <extracted text>","type":"new_api_error","code":"bad_response_status_code"}} |
Task Status Codes¶
Error Code List¶
| Error Code | Error Type | HTTP Status | System | Description (Chinese) | Description (English) | Trigger Condition | Example Client Response |
|---|---|---|---|---|---|---|---|
| 1 | midjourney_success | 200 | Midjourney | 任务提交成功 | Task submitted successfully | MJ proxy accepted and queued the task | {"code":1,"description":"提交成功","result":"<task_id>"} |
| 4 | midjourney_error | 400 | Midjourney | 请求参数错误 | Invalid request parameters | Missing required params (e.g. prompt) or bad type | {"code":4,"description":"<error detail>"} |
| 21 | midjourney_info | 200 | Midjourney | 任务已存在 | Task already exists | Duplicate submission of an existing/in-progress task | {"code":21,"description":"任务已存在","result":"<task_id>"} |
| 22 | midjourney_info | 200 | Midjourney | 任务排队中 | Task queued | Task submitted but there are queued tasks ahead | {"code":22,"description":"排队中，前面还有 N 个任务"} |
| 23 | midjourney_error | 429 | Midjourney | 队列已满 | Queue is full | MJ proxy task queue reached capacity | {"code":23,"description":"队列已满，请稍后尝试"} |
| 24 | midjourney_error | 400 | Midjourney | Prompt 包含敏感词 | Prompt contains banned words | Prompt triggered Midjourney content filter | {"code":24,"description":"可能包含敏感词"} |
| 3 | midjourney_error | 403 | Midjourney | 无可用账号实例 | No available account | No available Discord account in MJ proxy backend | {"code":3,"description":"No available account instance"} |
| 30 | midjourney_error | 429 | Midjourney | 分组负载饱和 | Group load saturated | Concurrent requests for group reached the limit | {"code":30,"description":"当前分组负载已饱和"} |
| task_not_exist | task_error | 404 | Task System | 任务不存在 | Task not found | task_id not found in DB or not owned by user |
{"code":"task_not_exist","message":"查询的任务 ID 不存在"} |
| quota_not_enough | task_error | 403 | Task System | 任务额度不足 | Insufficient quota for task | User balance not enough for estimated task cost | {"code":"quota_not_enough","message":"任务额度计算失败或余额不足"} |
| invalid_api_platform | task_error | 400 | Task System | 无效的平台参数 | Invalid platform parameter | Unsupported platform type (e.g. typo) | {"code":"invalid_api_platform","message":"invalid api platform: <platform>"} |
| fail_to_fetch_task | task_error | Upstream status code | Task System | 获取任务失败 | Failed to fetch task from upstream | Upstream returned error when querying task status | {"code":"fail_to_fetch_task","message":"<upstream error detail>"} |
Internal Error Codes¶
Internal errors generated by the New API during different request processing stages.
Error Code List¶
| Error Code | Error Type | HTTP Status | Stage | Description (Chinese) | Description (English) | Typical Cause | Suggested Action |
|---|---|---|---|---|---|---|---|
| invalid_request | new_api_error | 400 | Request parsing | 无效的请求格式或参数 | Invalid request format or parameters | Malformed JSON body, missing required fields, empty model name | Check request format against OpenAI spec |
| sensitive_words_detected | new_api_error | 400 | Content moderation | 请求内容包含敏感词 | Sensitive words detected | Prompt hits configured sensitive word list | Modify prompt or ask admin to adjust list |
| insufficient_user_quota | new_api_error | 403 | Pre-charge | 用户额度不足 | Insufficient user quota | Account balance is 0 or below estimated cost | Recharge or ask admin to increase quota |
| pre_consume_token_quota_failed | new_api_error | 403 | Pre-charge | 预扣费失败 | Pre-consume quota failed | Token quota exhausted or limit reached | Check token quota or use another token |
| get_channel_failed | new_api_error | 500 | Channel selection | 无可用渠道 | No available channel | All channels disabled, model not mapped, or all offline | Check channel status and model mapping |
| count_token_failed | new_api_error | 500 | Token counting | Token 数量计算失败 | Token count failed | Tokenizer error or malformed content | Contact technical support |
| model_price_error | new_api_error | 500 | Pricing lookup | 模型定价信息缺失 | Model pricing not configured | Model price not configured in admin panel | Configure model price in "Model Pricing" |
| read_request_body_failed | new_api_error | 400 | Request read | 读取请求体失败 | Failed to read request body | Request body too large or connection interrupted | Reduce body size or check network |
| access_denied | new_api_error | 403 | Authentication | 拒绝访问 | Access denied | IP not in whitelist, token invalid, or user banned | Check IP whitelist or token validity |
| model_not_found | new_api_error | 404 | Model lookup | 模型未找到 | Model not found | Model not available in configured channels | Check model name or add channel |
| prompt_blocked | new_api_error | 400 | Content filtering | 提示词被拦截 | Prompt blocked by filter | Hit OpenAI policy or custom filter rules | Modify prompt to avoid violations |
| convert_request_failed | new_api_error | 500 | Request conversion | 请求格式转换失败 | Request conversion failed | Channel type not supported for this endpoint/params | Check endpoint and channel compatibility |
| channel:no_available_key | channel_error | 500 | Channel key selection | 渠道无可用 Key | No available key | All API keys for this channel invalid or rate-limited | Rotate/add new API key |
| channel:invalid_key | channel_error | 401 | Channel key verify | 渠道 Key 无效 | Invalid channel key | Channel API key expired or revoked by upstream | Update channel API key |
| channel:response_time_exceeded | channel_error | 504 | Request timeout | 渠道响应超时 | Channel response timeout | Upstream response time exceeded system timeout | Increase timeout or check upstream status |
| do_request_failed | new_api_error | 500 | HTTP request | 请求上游失败 | Failed to send request to upstream | Network failure, DNS error, or connection refused | Check network and upstream status |
| api_not_implemented | new_api_error | 501 | Route matching | API 端点未实现 | API endpoint not implemented | Endpoint not implemented in current version | Wait for update or use another endpoint |