API 排错与上线检查

排错时先回到最小请求：正确的 Key、一个后台实际可用的模型、尽可能少的参数、stream: false。最小请求成功后，再逐项恢复高级参数。

模型占位符

排错示例中的 YOUR_MODEL_ID 必须替换为 DuckMans 后台中当前 Key 和分组实际可用的模型 ID。先调用 GET /models，不要通过猜测模型名来处理协议或权限错误。

示意图：一次只增加一个变量，先获得稳定的非流式最小结果；可复制的地址、命令和代码仍以正文为准。

先确认地址

配置类型	正确填写
OpenAI 兼容 Base URL	`https://duckmans.com/v1`
模型列表完整请求地址	`https://duckmans.com/v1/models`
Responses 完整请求地址	`https://duckmans.com/v1/responses`
Chat Completions 完整请求地址	`https://duckmans.com/v1/chat/completions`
Anthropic 服务前缀	`https://duckmans.com`
Anthropic Messages 完整请求地址	`https://duckmans.com/v1/messages`

不要得到 /v1/v1。OpenAI SDK 的 Base URL 不应包含 /responses 或 /chat/completions；Claude/Anthropic 客户端使用主站前缀并自行追加 /v1/messages。

最小诊断请求

bash

old_stty=$(stty -g)
trap 'stty "$old_stty"' EXIT INT TERM
printf "DuckMans API Key: "
stty -echo
IFS= read -r DUCKMANS_API_KEY
stty "$old_stty"
trap - EXIT INT TERM
printf '\n'
export DUCKMANS_API_KEY

curl -sS -D - https://duckmans.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DUCKMANS_API_KEY" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "只回复 ok"}],
    "stream": false
  }'

-D - 会显示响应头。分享排错信息前，删除或打码任何可能包含 Key、账户和请求内容的字段。

示意图：状态码用于分流，最终原因仍需结合错误体和请求上下文；可复制的地址、命令和代码仍以正文为准。

按状态码处理

状态或错误	常见原因	处理方法
`400 Bad Request`	JSON、字段类型或参数不受支持	检查 JSON；移除新增参数，用最小请求重试
`401 Unauthorized`	Key 错误、缺失、已删除或 Bearer 格式错误	重新复制 Key；检查 `Authorization: Bearer ...`
`403 Forbidden`	Key 分组或模型权限不匹配、账户状态限制	核对后台 Key 分组和模型权限
`404 Not Found`	URL 重复 `/v1`、Endpoint 路径不存在或协议不支持	区分 Base URL、Endpoint 路径与完整请求地址；确认当前路线支持所选协议
`429 Too Many Requests`	频率、并发或当前额度限制	降低并发，读取重试提示，使用带抖动的指数退避
`5xx`	服务或上游临时异常	保存请求时间和请求 ID；有限重试，持续出现时反馈
模型不存在或不可用	模型 ID 错误、分组不包含模型或渠道暂不可用	重新请求 `/models`，原样复制当前可用 ID
余额不足	账户或 Key 可用额度不足	在后台确认余额、Key 限额和分组状态
`Unsupported parameter`	当前模型、协议或渠道不支持该参数	删除错误点名的参数，从最小请求逐项加回

不要对 401、403、持续的 404 进行无休止重试；先修正认证、权限或地址。429 和临时 5xx 才适合有限次数的退避重试。

Responses 不可用

Responses 是否可用取决于客户端、Key 分组和上游渠道，未实测时不能视为默认能力。

使用最小 /responses 请求，去掉可选参数。
确认客户端的协议设置确实为 Responses。
核对 Key 分组是否支持该协议和目标模型。
如果客户端允许切换，测试 /chat/completions。
如果客户端强制使用 Responses，则需要选择明确支持 Responses 的分组和渠道。

Chat Completions 成功而 Responses 失败，通常说明协议路线不同，不代表 Key 本身一定无效。

流式输出异常

先把 stream 改为 false，确认非流式请求成功。
命令行测试使用 curl -N。
检查反向代理和 Web 框架是否缓冲响应。
确认解析器与 Endpoint 路径匹配：Responses 和 Chat Completions 的事件结构不同。
连接中断重试时，避免把已经展示的文本重复追加。

SDK 常见问题

环境变量未生效

在启动程序的同一个终端中设置 DUCKMANS_API_KEY，然后重新启动程序。不要为了绕过环境问题而把真实 Key 写死到源码。

路径出现 `/v1/v1`

将 SDK 的 base_url 或 baseURL 改为 https://duckmans.com/v1。不要在 SDK Base URL 后再手工添加 /v1、Endpoint 路径或完整请求地址。

客户端参数比 curl 多

先用最小 curl 验证服务，再逐项对比客户端发出的模型、Endpoint 路径、流式设置和额外参数。不要在日志中输出完整 Authorization 请求头。

示意图：支持材料必须移除完整 Key、Authorization、账户和私密内容；可复制的地址、命令和代码仍以正文为准。

上线检查清单

[ ] API Key 只保存在服务端环境变量或密钥管理服务中。
[ ] 日志、监控、异常上报和截图不会记录完整 Key。
[ ] OpenAI-compatible 客户端或 SDK 的 Base URL 为 https://duckmans.com/v1，没有重复 /v1。
[ ] Anthropic/Claude 客户端的服务前缀为 https://duckmans.com，最终请求到达 https://duckmans.com/v1/messages。
[ ] 模型 ID 来自后台当前可用列表，而不是写死的教程示例。
[ ] 已用目标 Key 和分组分别验证所选协议。
[ ] Responses 未经实测时，没有把它当作所有路线都可用的默认接口。
[ ] 请求设置了合理的连接、读取和总超时。
[ ] 只对可安全重放的 429 和临时 5xx 请求进行有限退避重试。
[ ] 流式客户端能处理完成事件、错误事件和中途断开。
[ ] 错误页面不会把上游完整响应、账户信息或 Key 返回给最终用户。

API 排错与上线检查 ​

先确认地址 ​

最小诊断请求 ​

按状态码处理 ​

Responses 不可用 ​

流式输出异常 ​

SDK 常见问题 ​

环境变量未生效 ​

路径出现 /v1/v1 ​

客户端参数比 curl 多 ​

上线检查清单 ​