报 504 timeout_error「Upstream timed out」怎么解决

同一个问题的其他写法

• unexpected status 504 Gateway Timeout: {"type":"error","error":{"type":"timeout_error","message":"Upstream timed out"}}, url: https://www.ccsub.net/api/v1/responses
• API Error: Request timed out

504 是在哪一步超时的

一个请求在 CCSub 里大致经过这几个阶段：鉴权和计费检查 → 选一条上游线路 → 把请求发给上游并等待它开始返回 → 把结果转发给你。504 发生在第三步：

• CCSub 等上游开始返回结果的时间上限约 65 秒。超过就算这条线路超时，会换一条线路再试。
• 所有换线重试共享一个约 90 秒 的时间预算，预算用完仍没有结果，就返回 504 Upstream timed out。
• 流式请求一旦开始输出，就不再受上面的首包限制，单个请求最长可以持续约 5 分钟。

所以 504 的意思不是「CCSub 挂了」，而是「这一次在规定时间内没等到上游开始回应」。

为什么非流式请求更容易 504

CCSub 近 30 天的 504 日志里，绝大部分发生在非流式请求上，而且一半以上来自程序直接调用接口（Go、Node 等的 HTTP 客户端），不是 Claude Code。原因在于非流式请求的工作方式：服务端要把整段回答全部生成完，才一次性返回。如果你让模型写一大段代码或长文，生成本身就可能超过一分钟，在部分线路上就会撞到等待上限。

改成流式之后，模型生成第一个字就开始返回，后面的内容边生成边推送。等待上限只约束「第一个字出现之前」这段时间，长输出不再是问题。

以 OpenAI SDK（Python）为例：

from openai import OpenAI

client = OpenAI(base_url="https://www.ccsub.net/api/v1", api_key="sk-你的密钥")
stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "写一个完整的 README"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Anthropic SDK 同理，用 client.messages.stream(...) 或在请求里传 stream=True。

上下文太长也会拖慢首字

即使是流式请求，模型也要先把整段输入处理完才能吐出第一个字。Claude Code 的长会话动辄十几万 Token，上游忙的时候首字等待会明显变长。处理方法：

1. 用 /compact 把历史压缩成摘要；话题已经换了就 /clear。
2. 不要把整个大文件读进对话，只取相关片段。
3. 一次性要求生成很长内容的任务，拆成几步分别完成。

和客户端自己的超时区分开

• API Error: 504 ... Upstream timed out：CCSub 返回的，按上面的方法处理。
• Request timed out、No response from API：Claude Code 本地的超时，默认 10 分钟（API_TIMEOUT_MS）。这种情况多半是请求根本没顺利到达 CCSub，比如本地代理卡住了，先看 连接报错。
• Codex 的流式空闲超时默认 5 分钟（stream_idle_timeout_ms），流中途断开时会显示 stream disconnected before completion。

超时失败的请求会释放预冻结的金额，不按用量计费。

常见问题

相关报错

• API Error: 503 {"type":"error","error":{"type":"overloaded_error","message":"上游线路暂时不可用，请稍后重试（不是您账户余额的问题） | Upstream temporarily unavailable, please retry shortly (this is not about your account balance)."}}CCSub 已自动换线重试过，这次仍没有可用线路。等一两分钟在原会话里发「继续」，或用 /model 换个型号；不扣费，也不是你的余额问题。
• API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"Invalid JSON in request body: Unterminated string in JSON at position 10407567 (line 1 column 10407568)"}}position 是上千万的数字 = 请求体太大、传输途中被截断：/compact 或 /clear、别反复贴大截图、大文件分段读。position 很小 = 发出去的 JSON 本身格式不对。
• stream disconnected before completion: stream closed before response.completed流在结束前断了。确认 base_url 是 https://www.ccsub.net/api/v1，去掉干扰终端的代理，过长的单轮任务调低推理强度或拆小，并在 provider 里调大 stream_max_retries。