文档 / 任务管理
文档 / 任务管理
异步任务失败错误码完整列表与排错指南:8 个顶层 code 枚举 + 上游 upstream.code 详解 + 重试策略。
本页汇总异步任务执行失败时返回的错误码完整列表与排错指南。错误码出现在任务响应的 error.code 字段中。
异步任务（图像 / 视频 / Suno 等）的失败不在提交响应里返回——提交成功只代表任务已入队。最终成败需通过 GET /v1/tasks/:id 轮询 status 与 error 字段判定。
任务执行失败（status: "failed"）时，响应中包含 error 对象：
{
"id": "task_xxx",
"object": "image.generation.task",
"status": "failed",
"model": "gpt-image-2",
"progress": 100,
"failed_at": 1778570120,
"error": {
"code": "upstream_error",
"message": "openai returned 400: ...",
"upstream": {
"provider": "openai",
"code": "content_policy_violation",
"message": "your request was flagged ..."
}
}
}| 字段 | 类型 | 说明 |
|---|---|---|
error.code | string | 顶层错误码（稳定枚举，见下方总览），客户端按它做粗分流 |
error.message | string | 用户友好的错误说明（已脱敏） |
error.upstream | object | 可选。上游 native 错误细节，仅执行阶段失败且 provider 拿到上游错误时出现 |
顶层 error.code 共 8 个稳定枚举，按阶段分类：
| 错误码 | 含义 | 可重试 |
|---|---|---|
invalid_request | 请求参数不合法（prompt/model 缺失、字段格式非法、n 超界等） | 修正参数后重试 |
model_not_supported | model 不在支持列表 | 换模型后重试 |
model_price_error | 模型计价配置异常（无定价 / 倍率非法） | 联系管理员 |
| 错误码 | 含义 | 可重试 |
|---|---|---|
task_not_found | 任务 ID 不存在或不属于当前调用者 | 检查 ID 后重试 |
| 错误码 | 含义 | 可重试 |
|---|---|---|
upstream_error | 上游返回 4xx（含内容违规、参数错误等） | 见 upstream.code 详解 |
upstream_unavailable | 上游 5xx 且重试耗尽 | 稍后重试 |
storage_error | 结果上传到云存储失败 | 稍后重试 |
internal_error | 网关内部异常 | 稍后重试 / 联系支持 |
失败任务会自动退还预扣的 quota。
error.upstream 上游错误详解#顶层 error.code 是粗分流。要细化原因（如区分"内容违规" vs "图像格式不对" vs "频率限制"），读 error.upstream.code——它是 provider 原生错误码，按上游不同而异。
| Provider | upstream.code 来源 | 示例 |
|---|---|---|
| openai | error.code（原文）；为空回落 error.type | content_policy_violation / invalid_image / rate_limit_exceeded |
| gemini（4xx） | error.status（原文）；为空回落 http_<code> | INVALID_ARGUMENT / PERMISSION_DENIED / RESOURCE_EXHAUSTED |
| gemini（200 但无图，prompt 整体被拦） | prompt_blocked:<blockReason> | prompt_blocked:OTHER / prompt_blocked:SAFETY |
| gemini（200 但无图，candidate 中途停） | finish_reason:<finishReason> | finish_reason:SAFETY / finish_reason:PROHIBITED_CONTENT |
Gemini 的"200 但无图"（响应成功但没产出图片，通常是内容触发安全拦截）视为 4xx upstream_error，不重试——内容被拦重试结果相同。
content_policy_violation#请求内容触发了安全审核机制被拦截，是最常见的失败原因。覆盖场景：
| 子类型 | 说明 | 典型消息 |
|---|---|---|
| 写实人物 | 上传含真实人脸的照片 | photorealistic people detected |
| 名人肖像 | 涉及名人或公众人物 | celebrity detected in image |
| 版权/商标 | 涉及品牌 Logo、商标、受版权保护角色 | third-party content violation |
| 成人/NSFW | 含裸露、性暗示内容 | nudity detected |
| 暴力/自残 | 含暴力、血腥、自残内容 | violence content blocked |
如何避免： 避免上传真人照片（改用插画 / 卡通风格）；移除品牌 Logo、商标、IP 角色；避免成人、暴力等敏感主题；用通用人物描述（如 "a person"），不要引用具体名人。
invalid_image / image_processing_error#系统无法正常处理输入图片。常见原因：图片 URL 无法访问（权限不足、CDN 限制、链接过期）；格式不支持（HEIC、AVIF、TIFF）；文件损坏；网络下载失败。
如何处理： 确保图片 URL 可公开访问；使用标准格式 JPG / PNG / WebP；改用文件上传接口替代 URL 方式；检查图片是否完整可打开。
image_dimension_mismatch#输入图片尺寸与请求参数不一致，常见于图生视频。如 aspect_ratio=1280x720 需上传 1280×720 横版图片。处理： 调整图片尺寸使其与 aspect_ratio 匹配，或改 aspect_ratio 适应图片。
rate_limit_exceeded / RESOURCE_EXHAUSTED#请求频率 / 并发超限，或上游资源暂时耗尽。处理： 降低请求频率（建议每次间隔 1-2 秒）；等待进行中任务完成后再提交；稍等 1-5 分钟后重试，系统会自动在多线路间切换。
import requests
import time
def poll_task_with_retry(task_id, api_key, max_retries=3):
"""带自动重试的任务轮询"""
headers = {"Authorization": f"Bearer {api_key}"}
for attempt in range(max_retries):
resp = requests.get(
f"https://api.apimax.ai/v1/tasks/{task_id}",
headers=headers
)
data = resp.json()
if data["status"] == "completed":
return data.get("data")
if data["status"] == "failed":
error = data.get("error", {})
code = error.get("code", "internal_error")
message = error.get("message", "")
# 请求阶段错误 — 不可重试，需修改请求
if code in ("invalid_request", "model_not_supported", "model_price_error"):
raise Exception(f"Client error [{code}]: {message}")
# task_not_found — 不可重试
if code == "task_not_found":
raise Exception(f"Task not found: {message}")
# 上游 4xx 内容违规 — 不可重试（重试结果相同）
upstream_code = error.get("upstream", {}).get("code", "")
if code == "upstream_error" and upstream_code in (
"content_policy_violation", "invalid_image", "image_dimension_mismatch"
):
raise Exception(f"Upstream [{upstream_code}]: {message}")
# 上游 5xx / 存储 / 内部错 — 可重试
if code in ("upstream_unavailable", "storage_error", "internal_error"):
if attempt < max_retries - 1:
time.sleep(2 ** attempt * 5) # 5s, 10s, 20s
continue
raise Exception(f"Retryable error [{code}]: {message}")
raise Exception(f"Error [{code}]: {message}")
# 任务仍在处理中
time.sleep(3)
raise Exception("Max polling attempts exceeded")| 不可重试（需修改请求） | 可重试（稍后重试） |
|---|---|
invalid_request — 修正参数 | upstream_unavailable — 等待后重试 |
model_not_supported — 换模型 | storage_error — 稍后重试 |
upstream_error（内容违规 / 图片问题）— 改内容或换图 | internal_error — 稍后重试 |
task_not_found — 检查 ID | upstream_error（频率限制 / 资源耗尽）— 降频后重试 |
遇到不确定的错误时，保留完整的 task_id 与 error 对象联系技术支持，便于定位。