HTTP 错误码
所有 API 错误响应使用统一格式：
{
"code": 40001,
"message": "错误描述",
"status": false,
"data": null
}
| HTTP | 业务码 | 含义 | 处理建议 |
|---|
| 200 | 20000 | 成功 | 正常处理 |
| 400 | 40001 | 参数错误 | 检查请求体 / Header |
| 401 | 40100 | 未授权（Key 无效或缺失） | 检查 Authorization 头 |
| 403 | 40300 | 权限不足 | 确认当前帐号能否调用该 web_app_id |
| 404 | 40400 | 资源不存在 | 检查 requestId / web_app_id |
| 429 | 42900 | 超出并发配额 | 降低并发 / 升级套餐 |
| 500 | 50000 | 服务内部错误 | 重试；持续失败请联系支持 |
| 503 | 50300 | 服务不可用（维护中） | 稍后重试 |
业务码与 HTTP 状态码可能不一致。确认任务是否成功时，请以响应体 code == 20000 且 status == true 为准。
任务状态机
任务从创建到终止的完整状态转换图：
| 状态 | 含义 | 是否产生费用 |
|---|
Queuing | 排队中 | 取消时不计费 |
Preparing | 准备中 | 免费 |
Running | 运行中 | 中断时仍产生部分费用 |
Success | 成功完成 | 完成全部计费 |
Failed | 失败 | 完全退款 |
Canceled | 已取消 | 免费 |
常见失败原因
1. web_app_id 不存在或无权限
{"code": 40400, "message": "web_app_id not found", "status": false}
{"code": 40001, "message": "invalid input_values: 84:CLIPTextEncode.text is required"}
input_values 完整 Schema，逐字段校对。
3. 输入文件 URL 不可访问
{"code": 20000, "status": true, "data": {"outputs": [{"audit_status": 4, "error_type": "INPUT_ACCESS_DENIED"}]}}
commit 接口返回的 BizyAir URL，而非任意公网 URL。
4. 内容审核不通过
{"outputs": [{"audit_status": 3, "error_type": "NSFW"}]}
5. Credits 余额不足
{"code": 42901, "message": "insufficient credits", "status": false}
/y/v1/wallet 确认余额。
6. 并发超限
{"code": 42900, "message": "too many concurrent tasks", "status": false}
重试策略
建议重试的错误
以下错误属于瞬态错误，安全重试：
| 情形 | 重试策略 |
|---|
| HTTP 429（限流） | 指数退避 + jitter（基座 2s，最多 5 次） |
| HTTP 500 / 502 / 503 / 504 | 指数退避 + jitter，最多 3 次 |
| 网络超时 / 连接重置 | 正常重试，最多 3 次 |
| WebHook 回调回逐 200 OK 以外 | 平台自动重试 |
不建议重试的错误
| 情形 | 处理 |
|---|
| HTTP 400 | 修改参数后才重新提交 |
| HTTP 401 | 重新获取 / 更新 API Key |
| HTTP 403 | 检查帐号权限 / 应用发布状态 |
| HTTP 404 | 检查 ID 是否拼写错误后重提 |
任务 Failed | 先看 error_type / error_msg，修正后重新提交 |
幂等性与 requestId
BizyAir 不自动对任务创建请求去重。如果你在没收到 requestId 的情况下盲重试 /create，可能产生重复任务与重复计费。建议：
- 发送前先在客户端生成业务层幂等销 key
- 若相同幂等销 key 对应的上一次已获
requestId，优先用 /detail 查询而非重新 /create
参考实现（Python）
import time, random, requests
def post_with_retry(url, headers, json_body, max_retries=3):
for attempt in range(max_retries + 1):
try:
resp = requests.post(url, headers=headers, json=json_body, timeout=(10, 60))
if resp.status_code == 200:
return resp.json()
if resp.status_code in (429, 500, 502, 503, 504) and attempt < max_retries:
wait = min(2 ** attempt + random.random(), 30)
time.sleep(wait); continue
resp.raise_for_status()
except (requests.ConnectionError, requests.Timeout):
if attempt < max_retries:
time.sleep(2 ** attempt); continue
raise
raise RuntimeError("exceeded retry budget")
