常见错误

准备：先保存一次完整失败 ​

准备好 HTTP 状态、响应正文、响应头和发生时间。只看到客户端弹窗里的“请求失败”通常不够。

$env:SUOXIE_API_KEY = '<API_KEY>'
curl.exe --include --show-error https://suoxie.codes/v1/models `
  -H "Authorization: Bearer $env:SUOXIE_API_KEY"

export SUOXIE_API_KEY='<API_KEY>'
curl --include --show-error https://suoxie.codes/v1/models \
  -H "Authorization: Bearer $SUOXIE_API_KEY"

复制结果时删除完整 Authorization 头和 Key。记录请求端点、模型、客户端版本，以及 X-Request-ID、X-Client-Request-ID、Retry-After 等实际出现的头；未出现的字段不要自行编造。

操作步骤与成功标志 ​

1. 用发生问题的同一把 Key 调用 GET /v1/models。
2. 如果模型列表失败，先解决网络、TLS 或认证，不修改客户端高级设置。
3. 如果模型列表成功，复制一个真实模型 ID，发送一次短、非流式的 cURL 请求。
4. 如果 cURL 成功而客户端失败，集中检查客户端 Base URL、协议、模型缓存和代理。
5. 如果 cURL 也失败，再根据状态码和响应错误类型继续。

每一步只改变一个变量。同时轮换 Key、改模型、改网络和重装客户端，会让问题更难定位。

成功标志： 同一把 Key 的 GET /v1/models 返回 HTTP 200，随后最小 Responses 请求返回 completed，并能在 Key 用量找到记录。

每次都按这个顺序 ​

顺序本身就是排查方法。GET /v1/models 不带请求体，可以检查服务地址、网络路径、TLS 和认证；最小 cURL 请求再加入一个精确模型和小型 JSON 请求体。两者都通过后，才排查桌面客户端、SDK、代理规则、流式设置、工具或图片。

记录失败时，只写下本地时间和时区、端点、状态码、脱敏后的响应正文、客户端及版本，以及实际出现的请求 ID。这样足以复现路径，同时不会暴露 Key 或用户内容。

失败时先检查：400 请求错误 ​

常见原因是 JSON 无效、必需字段缺失、端点和请求体不匹配，或上传体积超过限制。

• Responses 使用 input，Chat Completions 使用 messages，Messages 还需要对应版本头。
• 确认 Content-Type: application/json，复制的 JSON 没有注释、尾逗号或中文引号。
• 先删除工具、图片、流式和可选参数，回到文档中的最小请求。
• 请求体过大时可能返回 413；缩短上下文、减小文件或拆分任务，不要原样重试。

修正请求内容后再发送，400/413 不适合自动原样重试。

401 认证失败 ​

• 请求头必须是 Authorization: Bearer <API_KEY>，Bearer 后有一个空格。
• Key 不应包含复制进来的引号、空格或换行。
• 确认客户端没有把 Key 放到查询参数、普通 JSON 字段或错误的 provider 配置中。
• 在控制台检查 Key 是否已撤销、过期或被禁用。

若 /v1/models 也返回 401，问题在认证层。不要通过反复切换模型来解决；无法确认 Key 完整性时应创建新 Key，验证后撤销旧 Key。

创建替换 Key 前，先检查不易察觉的复制错误：首尾引号、末尾空格或换行。不要把旧 Key 或新 Key 的完整值贴进工单中供人比对。

403 权限或计费限制 ​

403 表示服务器识别了请求，但当前 Key、账户、分组或能力不允许执行；部分余额/计费错误也会映射为 403。

• 确认余额、订阅和 Key 限额。
• 确认 Key 分组允许目标模型、端点及图片等能力。
• 使用同一 Key 查询 /v1/models，不能用另一把 Key 的列表证明权限。
• 若设置了 IP 或其他访问限制，确认请求来源符合规则。

只有配置或账户状态改变后重试才有意义，403 不应原样高速重试。

若 403 出现在充值兑换页面，先检查登录账户和兑换入口，再按兑换码与钱包核对兑换记录与余额；不要用 API 分组切换处理充值 403。已有有效订阅但模型不可用时，检查订阅范围、选择分组和同一把 Key 的实时模型列表。

404 路径、模型或任务不存在 ​

先看响应正文区分对象：

• 路径问题：Base URL 缺少 /v1，或客户端拼成 /v1/v1/...。
• 模型问题：模型不在当前 Key 的实时列表，或分组没有配置该模型。
• 异步功能：对象存储/异步任务未启用时，提交端点可返回 404。
• 任务问题：task_id 错误、已过期，或任务记录不存在。

路径和模型 404 必须修正配置。任务 404 不要无限轮询；回到提交响应核对 poll_url、Key 和有效期。

首次配置客户端时，404 经常是字段填写位置错误：客户端可能要求 Base URL 为 https://suoxie.codes/v1，并自行追加端点。先把其日志中的最终 URL 与可用 cURL 命令对照，再修改 Key 或模型。

408、499 与客户端超时 ​

超时不等于服务一定没有执行：

• 408 表示请求在规定时间内未完成；499 常表示客户端先关闭连接。
• 检查客户端、反向代理和业务层是否有互相冲突的超时。
• 用短输入验证通路，再逐步恢复上下文、输出长度和工具调用。
• 长文本可使用流式输出；长图像任务改用异步端点。
• 产生费用或副作用的请求在重提前先查用量或任务状态。

429 限速、配额或并发 ​

429 可能来自等待队列、并发、RPM、时间窗口配额或上游限速。处理顺序：

1. 读取并遵守 Retry-After；若缺失，使用带随机抖动的指数退避。
2. 暂停所有调用方的同步重试，降低并发和请求频率。
3. 检查余额、Key 配额、分组限制和是否有另一台设备在使用同一 Key。
4. 为重试设置总截止时间和最大次数，不要无限循环。

不要固定每秒重试，也不要让 SDK、代理和业务代码各自重试三次。

5xx 服务或上游错误 ​

5xx 可以有限退避，但持续失败时应停止请求风暴。不要用大量换模型请求来“探测”恢复。

没有 HTTP 状态码 ​

初学者还常遇到以下情况：

安全边界：何时撤销 Key ​

安全边界：以下情况无需等待排错完成：Key 出现在公开仓库、截图或聊天中；用量出现陌生来源；设备丢失；日志错误地记录了 Authorization。立即撤销，创建替代 Key，更新服务后检查旧 Key 是否仍有请求。

下一步 ​

修复后，用相同的最小请求复测，并在 Key 用量中确认记录。若已通过，回到最初失败的客户端设置，只修改那一项；若问题仍可复现，再按联系支持模板提交脱敏信息。