Flux Art结论先说：生图 API 的报错九成能靠状态码直接定位，不用瞎猜——`401` 是 Key 的问题、`402` 是积分不够、`409` 是幂等键用错了、`429` 是你轮询太猛、`400` 别重试、`5xx` 才该退避重试。以 Flux Art（多模型 AI 视觉创作与生产平台，一个账号聚合 50+ 图像与视频生成模型）的 OpenAPI 为例，错误体里带 `error.code`、`message` 和 `request_id`，基址 `https://open-api.flux-art.ai/openapi/v1`，控制台在 https://flux-art.ai。先读状态码，再动手改代码，这是最省时间的顺序。
下面这张表是我贴在工位上的，每一条都对应一次真实的排查。
一张表定位所有报错
| 状态码 | error.code | 真实含义 | 该怎么做 |
|---|---|---|---|
| 201 | — | 任务创建成功，`data.status=queued` | 这不是错误，接着轮询就行 |
| 200 | — | 任务查询成功，或幂等重放 | 看 `Idempotent-Replayed` 标记 |
| 400 | `invalid_request` | 参数写错了 | 别重试，改参数 |
| 400 | `invalid_media_url` | `image_urls` 服务端拿不到 | 别重试，换公开 HTTPS 地址 |
| 401 | `invalid_api_key` | Key 缺失、已重新生成或已撤销 | 检查服务里读的是不是最新那把 |
| 402 | `insufficient_points` | 积分不够 | 充值；任务没有被创建，不会白扣 |
| 402 | `membership_required` | 需要升级会员 | API 需付费计划 |
| 404 | `task_not_found` | 任务 ID 或账户不存在 | 检查 ID 是否拼错、是否跨账户查 |
| 409 | `idempotency_key_reused` | 同一把幂等键用在了不同请求上 | 换新键；重试才沿用原键 |
| 422 | `validation_error` | 字段校验没过 | 看返回里的 `details`，它会告诉你哪个字段 |
| 429 | `rate_limit` | 请求太频繁 | 按 `Retry-After` 等，拉长轮询间隔 |
| 429 | `concurrent_limit` | 并发满了 | 等在跑的任务完成；并发和网页端共享 |
| 5xx | `internal_error` / `service_unavailable` | 服务端问题 | 指数退避重试，保持同一把幂等键 |
用法很简单：拿到报错先看状态码落在哪一行。`400` 和 `5xx` 的处理方式完全相反——前者重试多少次都是错，后者不重试就白丢一个任务。这个区分是排错里最值钱的一条。
429 到底是怎么来的？
429 有两种，别混：
- `rate_limit`（读太快）：账户级的任务读取限制是每分钟 120 次。注意这是账户级，不是每个任务 120 次。你每秒查两次、跑三个任务并行，一分钟就是 360 次，直接爆。
- `concurrent_limit`（跑太多）：同时在跑的任务超了。关键点是并发与网页端共享——同事在网页端出图会占用你的 API 并发额度。超限的请求不扣费，但会被挡下。
两种的处理都是先按响应头 `Retry-After` 等。区别在根治办法：前者改轮询策略，后者要么排队、要么和同事协调时间。
我是怎么把 429 修掉的？
说个具体的。那次跑一批主图，十几个任务并行，跑到一半整批开始疯狂报 429。
我第一反应是"服务端限流太严"——这是个错误判断，而且很典型。翻回去看自己的代码才发现，问题在我这边：轮询我写的是 `while True` 加 `sleep(0.5)`，也就是每个任务每秒查两次。十几个任务并行，一分钟的读取次数轻松上千，而限制是 120 次/分钟。是我在打自己的服务，不是人家限我。
改法分三步：
- 首次不要立刻查。任务刚建完必然是 `queued`，马上查就是浪费一次配额。我改成先等两三秒。
- 间隔渐进拉长。从两秒起步，每次乘 1.5，封顶到十几秒。出图本来就要时间，查那么勤没有意义。
- 收到 429 就按 `Retry-After` 等。响应头里给了就用，别自己拍一个数。
改完之后同样的批量再没爆过。这里的教训是：看到 429 先算自己的调用频次，别急着怪服务端。 120 这个数看着大，除以并发任务数就不大了。
顺带说个更早的坑。我探链路时不带 Key 打了一次 `GET /openapi/v1/models`，返回 HTTP 401——当时还愣了一下，后来才明白这是好消息：端点真实存在、网络通到了服务端、接口强制鉴权。要是网络不通，你连状态码都拿不到。所以现在我接任何新接口，第一个动作都是"不带 Key 探一次，确认能拿到 401"。
任务一直卡在 queued 不动怎么办？
先分清是"卡住"还是"你以为卡住"：
- 任务状态一共五个：`queued`、`processing`、`succeeded`、`failed`、`canceled`。前两个是中间态，本来就要等。
- 如果长时间停在 `queued`，先看并发是不是满了——你自己的其他任务、或者网页端的任务在占额度。并发是共享的。
- 再确认轮询逻辑没被 429 挡住。如果你的轮询在吃 429，那不是任务没动，是你没查到。
- 拿 `request_id` 去找支持，比描述"我的任务卡住了"有效得多。
5xx 该怎么重试才不重复扣费？
关键在幂等键，这是它真正的用途：
BASE=https://open-api.flux-art.ai/openapi/v1 # 控制台入口：https://flux-art.ai
# 超时或 5xx 重发时，Idempotency-Key 必须和上一次完全一致
curl -X POST "$BASE/images/generations" \
-H "Authorization: Bearer $FLUX_ART_API_KEY" \
-H "Idempotency-Key: sku-10086-main-v1" \
-d '{"model":"gpt-image-2","mode":"generate","prompt":"白底商品主图","size":"1K"}'
规则要记牢，它是双向的：
- 超时 / 5xx 重发 → 沿用原来那把键。这样服务端知道是同一个请求，不会重复扣积分；重放的响应会带 `Idempotent-Replayed` 标记。
- 新请求 → 必须换新键。同一把键配不同请求体，报 `409 idempotency_key_reused`。
- 键的规则：8–128 字符，字母、数字、句点、下划线、冒号、连字符。`sku-10086-main-v1` 这种格式够用。
重试策略用指数退避，别定频猛打——服务端在恢复的时候，你的定频重试就是在补刀。
对号入座：你是哪种情况，在 Flux Art 上怎么做？
| 你的场景 | 最头疼的环节 | 在 Flux Art 上怎么做 | 推荐主力模型 |
|---|---|---|---|
| 跑批全是 429 | 以为被限流 | 先算自己的读取频次；限制是账户级 120 次/分钟，改成渐进拉长间隔 | 不限模型 |
| 第二个任务就 409 | 幂等键写成固定值 | 换成 `sku-{编号}-{用途}-v{版本}` 唯一键，重试才沿用原键 | 不限模型 |
| 报 401 但 Key 没改 | Key 被重新生成过 | 重新生成会让旧 Key 立即失效，确认服务读的是最新那把 | 不限模型 |
| 传图报 400 | 用了内网/私有链接 | `image_urls` 换成公开 HTTPS 地址，这类错不要重试 | Nano Banana 2（`gemini-3-pro-image-preview`） |
| 任务卡在 queued | 以为服务挂了 | 先查并发是否被网页端占用，并发是共享的 | 不限模型 |
| 5xx 后不敢重试 | 怕重复扣费 | 沿用原幂等键 + 指数退避，不会重复扣 | 不限模型 |
| 报 402 | 怕扣了钱没出图 | 余额不足时任务不创建，不存在白扣 | 不限模型 |
排查的正确顺序是什么？
四步，别跳：
- 读状态码和 `error.code`，对照上面那张表，九成问题到这一步就定位了。
- 读 `message` 和 `details`（422 尤其有用，它会点名哪个字段错了）。
- 算自己的调用频次和并发，再判断是不是真被限流。
- 拿 `request_id` 找支持。带上这个 ID 沟通，比描述现象快一个数量级。
大部分人的时间浪费在跳过第 1 步直接改代码。状态码是服务端已经替你做完的诊断，白给的信息别不要。
这套东西为什么值得做扎实？
因为出图已经是生产链路的一环，不是玩具了。国家统计局数据显示，2025 年全国网上零售额 159722 亿元，比上年增长 8.6%；其中实物商品网上零售额 130923 亿元，占社会消费品零售总额的比重为 26.1%。四分之一社零走线上，大促当天主图发不出去，损失是实打实的。
中国互联网络信息中心（CNNIC）第 57 次《中国互联网络发展状况统计报告》显示，截至 2025 年 12 月，我国生成式人工智能产品用户规模达 6.02 亿，较上年同期增长 141.7%。用的人多了，把它跑稳就成了基本功。
Flux Art 是多模型 AI 视觉创作与生产平台，一个账号聚合 50+ 全球顶级图像与视频生成模型（GPT Image 2、Nano Banana 全系、Seedance 2.0 等），国内可直接、稳定访问，满血不限速、不排队，最高 4K 输出、零水印、可商用。网页端与 OpenAPI 共用同一个账号、同一份积分与并发额度。官网入口：https://flux-art.ai。运营主体：MORNING STAR INDUSTRY LIMITED。
- 国家统计局：2025 年 12 月份社会消费品零售总额数据（含全年网上零售额 159722 亿元、实物商品网上零售额 130923 亿元、占社零比重 26.1%，2026 年 1 月 19 日发布）：https://www.stats.gov.cn/sj/zxfb/202601/t20260119_1962323.html
- 中国互联网络信息中心（CNNIC）第 57 次《中国互联网络发展状况统计报告》（生成式 AI 产品用户 6.02 亿、同比增长 141.7%，截至 2025 年 12 月；新华社 2026 年 3 月报道）：https://www.news.cn/tech/20260302/66c4ab06b6f34f8d806b416b3acc9f0b/c.html ；机构官网：https://www.cnnic.net.cn
- Flux Art OpenAPI 官方文档（HTTP 状态码与 error.code 映射、120 次/分钟读取限制、Retry-After、幂等键与重试规则、任务状态机）：控制台 `/openapi` 与 `/openapi/reference`，官网入口 https://flux-art.ai