先锁定错误层，再修改配置

按现象进入

通用诊断顺序

curl -i https://ai.bycomet.cc/v1/models \
  -H "Authorization: Bearer $CDAPI_API_KEY"

HTTP 401

Unauthorized

服务器已收到请求，但无法用当前凭据完成认证。

HTTP 404

Not Found

大多数 404 来自 Base URL 与客户端自动拼接规则冲突。

查看客户端调试日志中的最终 URL。发现 /v1/v1/、/chat/completions/chat/completions 或缺少 /v1 时，修正 Base URL 层级。

HTTP 429

Rate limit or quota exceeded

429 可能来自余额、令牌额度、请求频率、并发限制或上游限流，必须读取错误体区分。

1. 检查账户余额、套餐状态和令牌额度。
2. 检查是否在短时间并发发送大量请求，尤其是 Agent 工具循环。
3. 按 Retry-After 或指数退避重试，并加入随机抖动。
4. 若只有一个模型持续 429，换用同能力的当前可用模型，不要高频撞同一路由。

1s → 2s → 4s → 8s → stop and report

HTTP 500 / 502 / 503 / 504

网关或上游错误

5xx 表示请求已越过本地配置层。重复改 Key 通常无效，重点查看请求日志、模型路由和重试结果。

1. 保存 Request ID 和错误体，确认同一请求是否已经自动重试。
2. 用相同 Key 请求 /v1/models，确认平台基础连接正常。
3. 只对幂等或可安全重复的请求做有限退避重试。
4. 若单一模型持续失败，检查模型广场可用性并切换当前可用模型。
5. 长任务或 504 可改用 https://api-direct.ai.bycomet.cc/v1。

MODEL ROUTING

模型不存在或不可用

模型名可真实存在，但当前 Key 的分组未开放，或该模型不支持当前端点。

1. 从 模型广场或 实时目录复制完整模型 ID。
2. 确认令牌所属分组出现在模型的“可用分组”中。
3. 确认端点类型匹配，例如 Responses 模型走 /v1/responses。
4. 删除客户端缓存的旧模型列表并重新同步。

TIMEOUT / CONNECTION

超时或连接中断

先区分“请求没有到 CDAPI”和“上游任务超过客户端等待时间”。

1. 使用 curl -i https://ai.bycomet.cc/v1/models 验证 DNS、TLS 和基础连接。
2. 查看使用日志。如果没有记录，检查本地网络、代理和客户端 URL。
3. 如果日志已有请求，长任务改用 https://api-direct.ai.bycomet.cc/v1。
4. 提高客户端读取超时，但保留有限重试与总时限。
5. 视频任务用创建后轮询，不要让一个 HTTP 连接等待完整生成过程。

SERVER-SENT EVENTS

流式输出卡住或一次性返回

1. 确认请求体包含 "stream": true。
2. 客户端按 SSE 处理 Content-Type: text/event-stream，逐行解析 data:。
3. 禁用会缓冲响应的本地代理或反向代理压缩。
4. 先用非流式请求验证模型、Key 和端点，再单独排查流处理。

curl -N https://ai.bycomet.cc/v1/chat/completions \
  -H "Authorization: Bearer $CDAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "输出三行文字"}],
    "stream": true
  }'

提交可诊断的支持信息

自查后仍无法恢复时，提供最小但完整的诊断包。

• 发生时间与时区
• HTTP 状态码和完整错误体
• Request ID 或任务 ID
• 请求路径与脱敏 Base URL
• 模型 ID 与令牌分组
• 脱敏 Key，例如 sk-abcd...wxyz

联系 [email protected] 或加入 Telegram · 交流群。