#流式响应与错误

大多数对话接口通过 SSE 流式返回，Realtime 使用 WebSocket。排查时先区分“请求没有到达 Geekit”“Geekit 拒绝请求”“上游失败”和“客户端没有正确显示响应”。

#SSE 基础

Chat Completions 和 Responses 都可以设置：

{
  "stream": true
}

curl 测试时使用 -N：

curl -N "$GEEKIT_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $GEEKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<模型 ID>",
    "messages": [{"role": "user", "content": "输出 1 到 5。"}],
    "stream": true
  }'

如果 curl 能持续输出，而应用界面一直空白，问题通常在客户端缓冲或事件解析。

#不同协议的流式结构

不能只替换 URL 而继续使用另一种协议的解析器。

#缓冲与超时

• 客户端应在收到事件时立即消费，不要等待响应结束。
• 读取超时必须覆盖模型首次输出和长任务所需时间。
• 连接空闲不一定表示失败，推理模型可能有较长首包时间。
• 客户端主动断开后，上游请求可能仍在结算；查看日志确认最终状态。
• 如果不同客户端都在同一时间失败，联系服务管理员排查网络或服务状态。

公开用户文档不提供反向代理和服务端超时配置。用户只需记录现象、时间、接口和请求 ID。

#常见 HTTP 状态码

#400 Bad Request

检查 JSON、必填字段、模型 ID、协议、文件格式和参数范围。把请求缩减到最小示例，再逐个恢复高级字段。

#401 Unauthorized

检查：

• 是否发送 Authorization: Bearer <令牌>。
• Claude 客户端的 x-api-key 是否填写 Geekit 令牌。
• Base URL 是否指向正确 Geekit 实例。
• 环境变量是否只在另一个终端会话中设置。

#403 Forbidden

令牌有效，但没有模型、分组或能力权限，或预扣时发现可用额度不足。重新查询 /v1/models 并检查余额；错误类型为 insufficient_user_quota 时不要按限流问题重试。

#429 Too Many Requests

表示触发速率或并发限制。降低并发与重试频率，并在日志中确认具体错误。

#5xx

表示 Geekit 或上游处理失败。先重试一次最小请求；持续失败时保存请求 ID、时间、模型和脱敏错误。

#模型不可用

出现模型不存在、无可用渠道或路由失败时：

1. 重新调用 /v1/models。
2. 精确复制模型 ID。
3. 确认协议与模型能力匹配。
4. 检查令牌是否限制了模型。
5. 在控制台日志中查看是否有请求记录。

#上游错误

Geekit 会尽量返回兼容当前协议的错误结构。上游可能返回繁忙、内容政策、区域限制、参数不支持或临时故障。不要把上游错误误判为令牌无效；以 HTTP 状态、错误类型和日志记录综合判断。

#重试原则

• 只对网络中断、限流和临时 5xx 做有限次数重试。
• 使用指数退避和随机抖动。
• 对非幂等任务谨慎重试，避免重复生成和重复计费。
• 400、401、403 应先修正请求或权限，不要自动重试。

需要提交问题时，按社区与支持中的清单脱敏信息。