错误码与限流

本文帮助你正确设置超时、并发，并处理常见 HTTP 错误。对外入口统一为 https://api.713812.xyz。

1. 建议并发与 RPM（按套餐）

套餐	建议并发	约 RPM	说明
Starter	≤ 3	6–12	个人 / 试用
Pro	≤ 8	16–30	内容团队
Biz	≤ 15	30–50	可工单申请上调

RPM 粗算：平均单图 15–30s 时，RPM ≈ 并发 × (60 / 平均秒耗)。对外请取保守值。

若收到 429 或风控类文案，立即降低并发并拉长间隔，勿继续加压。

2. 建议客户端超时

场景	建议 timeout	说明
1K / 默认 gpt-image-2	120s	多数请求足够
2K	120–180s	高峰加长
4K	180–300s	对齐服务端上限
网关整链	≥ 服务端 timeout	避免客户端先断

重试：对 408 / 429 / 502 / 503 / 504 使用指数退避（例如 2s、4s、8s），最多 3 次；对 400 / 401 / 403 / 内容安全 不要盲重试。

3. 常见 HTTP 错误

HTTP	典型含义	客户侧处理
400	参数错误、模型不存在、prompt 非法	修请求后重发
401	Key 无效 / 未传 / 已禁用	检查 Bearer；联系续费或换 Key
403	无权限、能力未开通	换有权限的 Key / 模型
408	上游瞬时过载	等待 3–5s 再试
429	限流 / 席位打满	尊重 Retry-After（若有），降并发
451 / 内容安全	提示词或参考图触发安全策略	改 prompt，不要换号狂重试
500/502/503/504	网关或上游短暂故障	退避重试；持续失败提单

网关可能把错误包成 type: new_api_error；以 message 与 HTTP 状态为准。

4. 安全并发实践

1. 客户端用全局信号量限制并发，而不是「打满再看 429」。
2. 批量任务用队列 + 固定 worker（如 3/8/15），失败入死信而非无限重试。
3. 观察到错误率升高或延迟 P95 > 120s：先砍一半并发。
4. 禁止用同一 Key 开数百线程扫模型；易触发风控并连坐。

5. 联调建议

上线或换 Key 后，先用 单 Key 串行 3 张图 做金丝雀验证，再缓慢爬坡并发。
超时与错误仍异常时，携带请求时间、模型 ID、HTTP 状态与响应摘要联系客服。