错误码与重试
适用于 HTTP API，CLI 和 MCP 会把这些错误原样带出（形如 403 模型额度不足，请先充值）。
状态码
| 状态码 | code | 含义 | 处理 |
|---|---|---|---|
| 400 | — | 模型不存在、参数或参考图不合法 | 对照 /generate/models 检查模型 id、参数、refs |
| 400 | MODEL_PRICE_MISSING | 该模型尚未配置价格，暂不可用 | 换一个模型，或联系管理员 |
| 401 | — | 没带 Key，或 Key 无效 / 已作废 | 检查 PHOENIX_MODEL_KEY 是否以 sk- 开头、是否被删除 |
| 403 | INSUFFICIENT_QUOTA | Key 的额度不足 | 到面板充值后重试，未调用上游、不会扣费 |
| 403 | MODEL_NOT_ENABLED | 该模型暂未上架（不在你的 Key 可用的模型列表里） | 用 /generate/models 返回的模型，或联系管理员上架 |
| 403 | NO_MODEL_KEY | 登录账号下没有可用的模型 Key，无法确认模型权限 | 到面板创建并启用一个模型 Key |
| 403 | — | 站点限制了生成权限（管理员设置了 WS_GENERATE_MIN_ROLE） | 联系管理员 |
| 404 | — | 记录不存在或不属于当前 Key | 确认 id 正确、使用的是同一个 Key / 账号 |
| 413 | — | 上传文件超过大小上限 | image ≤ 15 MB、video ≤ 60 MB、audio ≤ 30 MB |
| 429 | — | 触发限流（提交默认 20 次/分钟，上传 30 次/分钟、50 个/天） | 稍等再试，指数退避 |
| 500 | BILLING_STORE_ERROR | 计费系统暂时不可用，任务未提交 | 稍后重试 |
| 500 | BILLING_TARGET_NOT_FOUND | 用 Key 登录，但没能找到这把 Key 所属的账户，任务未提交 | 联系管理员 |
| 503 | MODEL_CHECK_UNAVAILABLE | 暂时无法确认模型是否可用（网关异常） | 稍后重试 |
| 5xx | — | 服务端或上游异常 | GET 请求退避重试；提交先查历史再决定 |
LLM 接口（/v1/*）的错误是 OpenAI 风格的 error 对象，401、429 的含义相同。
重试建议
- GET（查询、轮询、模型目录）：可以重试，最多 3 次，间隔 1s → 2s → 4s
- POST
/generate/submit：不要因为超时就自动重试。请求可能已经成功并创建了任务，重复提交会重复扣费。先用GET /generate/history或保存的id确认，再决定是否重新提交 - 任务
failed时，预扣的额度会自动退回，不需要手动处理
额度与计费
- 图像按次计费，LLM 按 token 计费，都从 Key 的额度里扣
- 提交时先预扣，成功后核销，失败全额退回，同一任务不会重复扣费或重复退款
- 用 Key 调用时，每一笔扣费都会关联到这把 Key 所属的用户，并记入 NewAPI 的使用日志（类型为消费，包含用户名、令牌名、模型、渠道和额度）；任务失败的退款也会各记一条
- 余额与用量请在面板查看