API 参考

API 错误码与重试

错误使用标准 HTTP 状态码和统一的 JSON 结构：code 稳定可供代码判断，message 给人看。

获取 API 密钥Wan 3 API 团队 · 更新于 2026年11月1日

JSON

json

{
  "error": {
    "code": "insufficient_credits",
    "message": "This render costs 30 credits; you have 12."
  }
}

状态码	错误码	含义
400	`invalid_request`	请求体或请求头无效，message 会指出哪个字段。
400	`media_unreachable`	媒体 URL 无法下载，或文件类型不支持。
401	`invalid_api_key`	缺少密钥、格式错误或已吊销。
402	`insufficient_credits`	积分不足，未扣费。
403	`account_disabled`	账号已被停用。
404	`not_found`	账号下没有该任务，或接口不存在。
409	`task_processing`	任务仍在生成，暂时无法删除。
422	`content_blocked`	提示词或素材被内容审核拦截，未扣费。
429	`rate_limited`	该密钥请求过多，请等待 Retry-After 后重试。
429	`too_many_running_tasks`	同时生成的任务太多，请等其中一个完成。
502	`upstream_error`	生成服务未能接收任务，积分已退回。
503	`service_unavailable`	API 或模型暂时不可用。

失败的任务

已受理但最终失败的任务，status 为 failed、refunded 为 true，error.code 为以下之一：

error.code	含义
`content_blocked`	生成结果被内容审核拦截。
`media_rejected`	参考图或首尾帧被拒绝，常见原因是包含真人。
`timeout`	生成时间过长被终止。
`service_unavailable`	生成服务暂时不可用。
`failed`	其他原因。修改提示词后重试通常可以成功。

免费调用与 402

新账号赠送 2 次免费调用，仅限最低价参数：模型的最低分辨率、最长 5 秒、文本或图片输入。免费调用消耗 0 积分，生成失败时会返还。请求无法支付时，API 返回 402，并附带原因、所需积分和购买链接。

json

{
  "error": {
    "code": "insufficient_credits",
    "reason": "free_calls_exhausted",
    "message": "Insufficient credits: this request costs 15 credits and the balance is 0. Nothing was charged. Your 2 free calls are used. Buy credits: …/credits/purchase?ref=api_402",
    "required_credits": 15,
    "balance": 0,
    "free_calls_remaining": 0,
    "purchase_url": "…/credits/purchase?ref=api_402"
  }
}

error.reason	含义
`free_calls_exhausted`	账号的免费调用已用完，且积分不足。
`free_call_not_eligible`	请求超出免费调用的参数范围（分辨率、时长或参考视频），或该账号不享有免费调用。
`insufficient_balance`	余额低于本次生成的费用。

重试

429、500、502 和 503 可退避重试，并带上相同的 Idempotency-Key，避免重复生成。400、401、402、403、422 不修改请求就不要重试。

上一篇模型与价格