docs: document upstream model config failure

docs/api.md

@@ -71,6 +71,8 @@ T-504/T-505 已实现用户端充值页基线：`/recharge` 走 Django session +
 | `order_not_found` | 充值订单不存在或不属于当前用户 | 404 |
 | `rate_limited` | 请求过于频繁，请稍后再试 | 429 |
 
+`upstream_error` 需要按错误消息继续区分：如果 `/api/v1/balance` 成功、`/api/v1/models` 中目标别名存在且 `pricing_status="priced"`，但生成接口返回 `502 upstream_error` 且消息为「上游模型配置不可用」，优先判定为**服务端上游模型运行配置问题**，不是客户端 payload 问题。常见原因是 `AI_KEY_ENCRYPTION_KEY` 与入库时不一致、`AiModel.api_key_encrypted` 无法解密、别名指向的 `AiModel` 缺 `url` / `model` / `api_type` / API Key，或 `api_type` 无可用 Provider。该错误路径不应最终扣点；修复按 [`deployment.md`](deployment.md) 的 AI 模型配置排查步骤执行。
+
 ## 对外接口
 
 > **重要约定**：`model` 字段传的是**能力别名**（如 `title-standard` / `image-hd`），不是具体供应商模型名。后台把别名映射到当前的具体模型，换供应商时调用方零改动。供应商特有参数放 `parameters`，但只允许 Provider 白名单内的安全参数透传；`model`、`n`、`size`、`resolution`、`messages`、`image*` 等核心/计费字段由服务端固定，调用方传入时忽略。