[DOCS] Document the non-streaming API fallback mechanism, including its token cap and timeout behavior

Documentation Type

other

Documentation Location

https://code.claude.com/docs/en/how-claude-code-works

Section/Topic

• https://code.claude.com/docs/en/how-claude-code-works — primary candidate for explaining the fallback mechanism as part of how Claude Code communicates with the API
• https://code.claude.com/docs/en/env-vars — secondary candidate if there are or will be env vars controlling this behavior
• https://code.claude.com/docs/en/troubleshooting — tertiary candidate for a note explaining why responses may appear truncated in certain network environments

Current Documentation

None of the documentation pages — including how-claude-code-works.md, settings.md, env-vars.md, cli-reference.md, or troubleshooting.md — mention the non-streaming fallback mechanism. Users encountering truncated responses or hangs caused by the fallback path have no documentation to consult.

The only public record of this mechanism is in changelog entries:

• v2.1.79: "Improved non-streaming API fallback with a 2-minute per-attempt timeout, preventing sessions from hanging indefinitely"
• v2.1.83: "Increased non-streaming fallback token cap (21k → 64k) and timeout (120s → 300s local) so fallback requests are less likely to be truncated"

What's Wrong or Missing?

The docs should explain:

• What the non-streaming fallback is: an alternate request mode Claude Code uses when streaming is unavailable (e.g., due to proxy incompatibility, network conditions, or API errors)
• That fallback requests have a maximum output token limit (currently 64k) — responses longer than this cap may be truncated
• That fallback requests have a per-attempt timeout (currently 300s locally) — requests that exceed this will fail rather than hang indefinitely
• Under what conditions the fallback is triggered (e.g., streaming endpoint returns a 404, gateway incompatibility)
• Practical guidance for users in environments where fallback is common (e.g., certain LLM gateway configurations)

Suggested Improvement

1. Navigate to https://code.claude.com/docs/en/how-claude-code-works
2. Search for "non-streaming", "fallback", "token cap", or "truncat"
3. Observe: no results — the mechanism is not described anywhere in the docs

Impact

Medium - Makes feature difficult to understand

Additional Context

• Changelog v2.1.83 entry: "Increased non-streaming fallback token cap (21k → 64k) and timeout (120s → 300s local) so fallback requests are less likely to be truncated"
• Related changelog v2.1.79: "Improved non-streaming API fallback with a 2-minute per-attempt timeout, preventing sessions from hanging indefinitely"
• Related changelog v2.1.79: "Fixed cost and token usage not being tracked when the API falls back to non-streaming mode"
• Related changelog (earlier): "Fixed API proxy compatibility issue where 404 errors on streaming endpoints no longer triggered non-streaming fallback"