错误与限流
状态码
| 码 | 意思 | 你该怎么办 |
|---|---|---|
400 | 参数不对，或者你要的能力当前没有上游支持 | 看 error 里的原因，别重试 |
401 | 没带 Key，或者 Key 不对 | 检查 header，看 认证 |
403 | 身份不够 | 多半是拿账户 Key 打了管理类接口，换租户 Key |
404 | 资源不存在，或者不是你的 | 别人的模板、别人的钩子、别人的账户都是 404 |
429 | 超限流 | 退避后重试 |
限流
| 什么 | 多少 |
|---|---|
| 出图 | 120 次/小时 |
| Chat | 300 次/小时 |
| 素材上传 | 同一归属 120 个/小时 |
几条重要的错误口径
不支持的能力返回 400，不静默降级
要透明背景但当前没有支持的上游 → 400 并说明原因，不会给你白底图。 要局部重绘但没有支持蒙版的上游 → 400「当前无可用上游」。
为什么不降级
白底图看起来完全正常。静默降级只会让你以为参数写错了， 反复调参、反复重试、反复花钱，还找不到原因。
前端遇到这类 400 该展示「该能力暂不可用」，而不是当成普通失败去重试。
漏填模板必填项返回 400
占位符原样进提示词会直接出废图。挡在前面比让你白花一次钱好。
视频档次配不上参数，提交时就拒
duration 超出该档次的范围、resolution 那一档不支持 —— 都在提交时返回 400，不会让你白等上游。
拿不准就别传 model，让系统自动挑。见选档次。
素材类型只信字节
声明 png 实际是 mp3 → 400，且不写进素材库。见素材上传。
异步任务 5 分钟无进展判死
图片转模板这类异步任务，超过 5 分钟没进展会被判 failed， error 里写明是超时兜底、不是模型失败。
为什么宁可判死
异步跑在平台的后台通道上，被中断时代码没有机会写状态。 与其让你轮询一个永远 pending 的任务，不如明确告诉你它没了。
出图任务失败 ≠ 接口报错
POST /api/generate 返回 200 只代表任务收下了。 真正的成败在回调或 GET /api/jobs 里的 status：
status: "failed"时error写原因- 失败的任务不计入
gen_quota