Fix "504 timeout_error: Upstream timed out"

Other forms of the same error

• 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

Where in the pipeline the timeout happens

Inside CCSub a request goes roughly like this: authentication and billing checks, pick an upstream line, send the request and wait for the upstream to start responding, then relay the result back to you. A 504 happens in step three:

• CCSub waits about 65 seconds for an upstream to start returning data. Past that, the line counts as timed out and the request moves to another line.
• All of those failover attempts share a budget of about 90 seconds. If the budget runs out with nothing to show, you get 504 Upstream timed out.
• Once a streaming response has started, that first-byte limit no longer applies, and a single request can keep streaming for about 5 minutes.

So a 504 doesn't mean CCSub is down. It means the upstream didn't start answering within the allotted time on this attempt.

Why non-streaming requests hit 504 far more often

In CCSub's logs from the last 30 days, the vast majority of 504s happened on non-streaming requests, and more than half came from programs calling the API directly (Go and Node HTTP clients) rather than from Claude Code. The reason is how non-streaming works: the server has to generate the entire answer before it sends anything. Ask for a big block of code or a long document and generation alone can take over a minute, which on some lines collides with the wait limit.

With streaming, the response starts flowing as soon as the first token is ready and continues as it's generated. The limit only covers the time before that first token, so long outputs stop being a problem.

With the OpenAI Python SDK, for example:

from openai import OpenAI

client = OpenAI(base_url="https://www.ccsub.net/api/v1", api_key="sk-your-key")
stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Write a complete README"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

The Anthropic SDK works the same way: use client.messages.stream(...) or pass stream=True.

Long contexts slow the first token too

Even with streaming, the model has to process the whole input before it can emit anything. Long Claude Code sessions easily reach well over a hundred thousand tokens, and when the upstream is busy the wait for the first token stretches. To keep it down:

1. Run /compact to replace the history with a summary, or /clear if you've moved on.
2. Don't read entire large files into the conversation — pull out the relevant parts.
3. Split tasks that need a very long output into several steps.

Don't confuse it with client-side timeouts

• API Error: 504 ... Upstream timed out — returned by CCSub. Use the fixes above.
• Request timed out or No response from API — Claude Code's own timeout, 10 minutes by default (API_TIMEOUT_MS). This usually means the request never got to CCSub cleanly, for example because a local proxy stalled. See connection errors.
• Codex's streaming idle timeout defaults to 5 minutes (stream_idle_timeout_ms). When a stream drops mid-way you'll see stream disconnected before completion.

Requests that fail with a timeout release their balance hold and aren't charged for usage.

FAQ

Related errors

• API Error: 503 {"type":"error","error":{"type":"overloaded_error","message":"上游线路暂时不可用，请稍后重试（不是您账户余额的问题） | Upstream temporarily unavailable, please retry shortly (this is not about your account balance)."}}CCSub already failed over between lines and none was free at that moment. Wait a minute and type "continue", or switch models with /model. Not billed, and not about your balance.
• 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)"}}A position in the millions means the body was truncated in transit: /compact or /clear, stop re-pasting big screenshots, read large files in chunks. A tiny position means the JSON itself is malformed.
• stream disconnected before completion: stream closed before response.completedThe stream dropped before it finished. Make sure base_url is https://www.ccsub.net/api/v1, take local proxies out of the path, shorten very long turns, and raise stream_max_retries on the provider.