How to Fix Stream Idle Timeout – Partial Response Received?
If you see “API error: stream idle timeout – partial response received”, it usually means the request started, some response data came back, then the stream stayed quiet for too long. At that point, the client, proxy, gateway, or server closed the connection before the full response finished.
This kind of error can be tricky because the API did not fail right at the start. Part of the response already arrived. So the real job is to find out where the stream stopped and which layer decided it had waited long enough.
What Does “Stream Idle Timeout – Partial Response Received” Mean?
A stream idle timeout happens when an API connection stays open but no new usable data arrives for longer than the allowed idle period. Since some response chunks were already received, the client reports a partial response instead of a complete connection failure.
This is not always the same as a normal request timeout. A connection timeout can happen before the request starts properly, while a read or idle timeout happens after the connection is already active. A total request timeout may also stop a request simply because the full operation took too long.
The main thing to remember is simple: the stream started, then there was a long gap with no new data.
Why Does the API Stream Idle Timeout Happen?
There is no single cause behind every stream idle timeout. The error can come from the local API client, the network path, a reverse proxy, an API gateway, or the backend itself.
Common causes include:
- A temporary API slowdown
- A client read timeout that is too short
- Large prompts or large requested output
- A VPN or proxy interrupting the stream
- A reverse proxy closing idle connections
- An API gateway timeout
- Response buffering
- Slow external API calls
- Slow database queries
- High server load
- Worker or connection limits
- An outdated SDK or HTTP client
Sometimes the API provider is the problem. Other times, the provider is fine and a middle layer closes the stream first. That is why it helps to test the request in a controlled way instead of changing every timeout at once.
How to Fix API Error: Stream Idle Timeout – Partial Response Received
Start with the simplest checks and test the same request after each meaningful change. If you change five things at once, you may fix the issue without knowing what really caused it.
1. Retry the Request and Check API Service Status
Try the same request once more. A short network interruption or temporary provider slowdown can cause a streamed response to stop even when your setup is correct.
If the retry works, the first failure may have been temporary. If it fails again in the same way, check the API provider’s official status page if one is available.
Do not keep retrying the request in a tight loop. Repeated failures are a sign that you should move on and test the stream path properly.
2. Test the Same Request Without Streaming
If the API supports both streaming and non-streaming responses, run the same request without streaming. Keep the prompt, model, payload, and other settings as close as possible to the original request.
The result helps narrow things down:
- If non-streaming works, focus on stream handling, read timeout, buffering, proxy, or gateway settings.
- If both modes fail, look more closely at request size, backend delay, network problems, or API availability.
This is one of the fastest ways to separate a streaming-specific issue from a general API problem. It saves a lot of random testing.
3. Reduce the Request Size or Requested Output
Large API requests can take longer to process. A big prompt, long context, large attachment, or very long requested output can create longer gaps between response chunks.
Try a smaller version of the same request. Shorten the input, reduce the output size, or remove extra data that is not needed for the test.
If the smaller request works but the full request fails, you have a useful clue. The request may be taking long enough to hit an idle or read timeout somewhere in the path.
That does not mean large requests always fail. It means larger work can expose timeout settings that never show up during lighter requests.
4. Increase the Client Read or Stream Timeout
Your API server may still be working while the local client has already stopped waiting. This happens when the HTTP library or SDK uses a read timeout that is too short for the time between streamed chunks.
Check the timeout settings in the client that sends the request. Do not confuse connection timeout with read timeout.
A sensible order is:
- Identify the SDK or HTTP client making the request.
- Find its current timeout settings.
- Look for a read timeout, stream timeout, or similar setting.
- Increase only the setting related to waiting for response data.
- Run the same request again and compare the result.
Do not copy a random timeout value from another framework. Different SDKs use different names and defaults.
Also, increasing the timeout is not a real fix if the backend is frozen. It only helps when the client gives up too early while the server is still working.
5. Update the API SDK or HTTP Client
An older SDK can have bugs around streaming, connection reuse, timeouts, or retry handling. If your project has not been updated in a while, check which version of the API SDK and HTTP client you are using.
Review the release notes before updating production code. A newer version can change default timeout behavior or streaming support, but it can also include breaking changes.
Do not assume an update will automatically solve the error. Think of it as a way to rule out old client behavior that may already have been fixed.
If the issue started right after an upgrade, compare with the last known working version too. That can be just as useful.
6. Disable VPN or Proxy and Test Another Network
Streaming requests stay open longer than normal web requests. Because of that, a VPN, proxy, firewall, or unstable network can break the stream even while normal browsing still works.
Try the request without an optional VPN or proxy. If possible, test from another stable connection as well.
For example, you might compare office Wi-Fi with a mobile hotspot, or one server network with another. If the request works on one connection but fails on the other, the network path becomes a stronger suspect.
Do not bypass required company or school security controls. If you are on a managed network, ask the administrator whether long-lived HTTP or SSE connections are being closed.
7. Check Reverse Proxy, CDN, Load Balancer, and Gateway Timeouts
This is where many stream problems hide. Your API request may travel through several layers before it reaches the real backend.
A common request path looks like this:
Client → CDN or reverse proxy → load balancer → application → API or backend
Each layer can have its own timeout. Your application may allow a request to run for several minutes, while a proxy in front of it may close the connection much sooner.
Check settings related to:
- Idle timeout
- Upstream or read timeout
- Maximum request duration
- Keep-alive behavior
- Long-lived connection support
If you only increase the timeout inside the app, nothing may change because the proxy or gateway still closes the stream first.
This is especially important in self-hosted setups. Nginx, cloud gateways, CDNs, and load balancers can all sit between the client and backend, and they do not always share the same limits.
8. Check Response Buffering
Sometimes the backend is producing data, but a proxy or gateway holds that data instead of forwarding it right away. The client sees a long quiet gap, even though the backend is still working.
One sign is that chunks arrive in large groups instead of appearing steadily. Another sign is that direct backend access works, but the same request through a proxy times out.
Check whether:
- The intermediary buffers streamed responses
- Response chunks are flushed as they are produced
- SSE or chunked responses are handled correctly
- A gateway waits for a larger buffer before forwarding data
If it is safe in your setup, compare the direct backend route with the proxied route. If direct streaming works but the proxy path fails, you have narrowed the problem down a lot.
9. Check Slow Backend Tasks, Tool Calls, or External APIs
The stream can go quiet while your backend waits for something else. This may be a database query, another API, a tool call, a model step, or a queued worker.
Imagine the stream starts normally, then your application calls an external service halfway through. If that service takes too long, no new chunks may be sent during that wait. A client or proxy can then hit its idle timeout.
Measure the time spent in each backend stage. Look at database timing, external API calls, worker logs, and tool execution time.
Do not only measure the total request time. The gap between chunks is often more useful than the final duration when you are dealing with an idle timeout.
10. Check Server CPU, Memory, Storage, and Worker Limits
This section mainly applies to self-hosted APIs, local AI servers, custom gateways, and apps that sit between the user and another API.
High CPU use can slow response generation. Low memory can cause workers to restart. Full storage can break temporary files or logs in some systems.
Check for:
- CPU saturation
- Memory pressure
- Very low free disk space
- Worker crashes or restarts
- Connection pool limits
- Too many requests running at the same time
Concurrency is easy to miss. One request may work perfectly on an idle server, then fail once many users connect.
Storage is not a common direct cause for someone using a normal hosted API. It matters more when you control the server or an intermediate application.
11. Add Safe Retry and Partial-Response Recovery Logic
Some streaming failures can still happen even after the system is configured well. Your application should handle them without turning one interrupted stream into a complete failure.
Use controlled retries rather than an endless loop. A short delay between retries helps, and that delay can increase after each failed attempt.
Be careful with requests that create or change data. Retrying a non-idempotent request can cause the same action to happen twice. This matters for payments, messages, account changes, or any endpoint that performs a real action.
If part of the response already arrived, think about whether it should be kept. Throwing away useful partial output is not always necessary.
Some APIs may support continuation or resume-style behavior. If yours does, that can be better than starting the whole request again.
12. Log Chunk Timing and Request IDs
When the error keeps happening, logs can show you exactly where the stream becomes idle. This is much better than guessing.
Record these points when possible:
- Request start time
- Time the connection was established
- Time the first response chunk arrived
- Time the last successful chunk arrived
- Time the timeout happened
- Request ID or trace ID
Now compare several failed requests. If the stream stops after almost the same amount of idle time every run, that often points toward a fixed timeout layer.
You can also compare client, proxy, and backend logs using the same request ID. This helps show whether the backend was still working after the client had already given up.
Before sharing logs, remove API keys, authorization headers, tokens, private endpoints, and sensitive payload data.
How Can You Prevent Stream Idle Timeout Errors?
Once the issue is fixed, check the whole request path instead of only the setting that caused the last failure. The client, proxy, gateway, and backend should have timeout values that make sense together. If one layer is much shorter than the others, it can still end the stream early.
A few habits help:
- Keep API SDKs and HTTP clients updated
- Use sensible read and stream timeouts
- Keep proxy and gateway timeout limits aligned
- Avoid unnecessarily large requests
- Watch the time between stream chunks
- Add controlled retry handling
- Monitor slow backend dependencies
- Save request IDs and timing data for failed requests
The goal is not to make every timeout extremely large. That can hide slow or stuck requests. Better timing data and cleaner timeout settings usually work much better.
Final Thoughts
The API error: stream idle timeout – partial response received means the request got far enough to return some data, then the stream stopped producing new data for too long. Start with a retry, test the same request without streaming, reduce the request size, and check the client read timeout.
If the problem continues, move outward through the network, reverse proxy, gateway, buffering, and backend. The most useful clue is often the timing. If the failure happens after nearly the same idle period every time, look hard at fixed timeout limits.
If you are still seeing the error, comment with one detail: does the same request work when streaming is turned off?
