If you see “API error: stream idle timeout – partial response received”, it usually means the API started sending data, but the stream stopped before the full response arrived. You may get half a message, incomplete JSON, a cut-off generated answer, or an application error after some data has already loaded.
This is a little different from an API request that fails immediately. The connection worked at first. Something then caused the stream to stay inactive long enough for a timeout to trigger. That “something” might be your API client, network, VPN, proxy, server, SDK, or even an API gateway sitting between your app and the provider.
This guide is for developers, API users, automation users, and anyone running an app that depends on streamed API responses. We’ll start with the easier checks, then move into timeout settings, stream handling, reverse proxies, and server-side problems.
What Does “Stream Idle Timeout – Partial Response Received” Mean?
A stream idle timeout happens when an API connection is open but no new data arrives for longer than the allowed idle period. Since the server already sent some response chunks before the timeout, your application reports that a partial response was received. So the request was not completely unsuccessful, but it also did not finish normally.
It helps to separate this from a few similar timeout errors:
| Error Type | When It Usually Happens | Common Reason |
|---|---|---|
| Connection timeout | Before a connection is established | Server unreachable, DNS issue, blocked connection |
| Read or idle timeout | While waiting for more response data | Slow stream, network interruption, proxy timeout |
| Total request timeout | Request runs longer than the allowed total time | Long-running request or strict client limit |
| Partial response error | Some data arrives, then the stream fails | Interrupted stream, timeout, app or server issue |
The wording varies between SDKs and services, but the main idea stays the same. Your app received something, then stopped getting new stream data before the response was properly completed.
Why Does the API Stream Idle Timeout Happen?
There isn’t one single cause behind this error. Streaming requests stay open longer than normal requests, so more things can interrupt them. A short API call might finish before a weak connection causes trouble, while a long streaming request has much more time to hit a network or timeout problem.
Common causes include:
- The API client has a read or idle timeout that is too short.
- Your internet connection briefly drops or becomes unstable.
- A VPN or proxy interrupts the long-lived connection.
- The API provider is overloaded or temporarily slow.
- A reverse proxy closes the stream before the upstream request finishes.
- A gateway or load balancer has its own idle timeout.
- The request asks for a very large or long response.
- Too many requests are running at the same time.
- The SDK has a streaming bug or outdated connection handling.
- Your application stops reading response chunks correctly.
- A server process crashes, restarts, or runs out of resources.
- Proxy buffering delays chunks long enough to make another layer think the stream is idle.
So, yeah, changing one timeout value isn’t always enough. The useful part is figuring out which layer is ending the connection.
How to Fix API Error: Stream Idle Timeout – Partial Response Received
Start with the simple tests first. Retry the request once, check the API service, test your network, and compare streaming with a normal non-streaming request. If the error keeps coming back, move deeper into timeout settings, SDK behavior, application logs, and proxy configuration.
If you control the backend that sits between your app and the API, don’t only check the client. Your reverse proxy, API gateway, CDN, serverless platform, or load balancer may have a separate connection limit.
1. Retry the API Request Once
Sometimes the stream dies because of a temporary network hiccup or short server delay. Retrying the same request once is a quick way to see whether the problem was temporary. If the second request finishes normally and the error rarely happens, you may be dealing with an intermittent connection or provider issue rather than a broken configuration.
Don’t turn this into endless retrying, though. Repeating failed requests immediately can make rate limits or server pressure worse. It can also cause duplicate actions if the API request creates an order, sends a message, changes data, or performs another action with side effects. For those requests, proper idempotency or duplicate protection matters.
2. Check Whether the API Provider Is Having Problems
Before changing code, make sure the API itself is working normally. A provider may be dealing with high traffic, degraded performance, slow model responses, or an issue affecting streaming connections only.
Check a few things:
- Look at the provider’s service status.
- Try another endpoint or model if the service supports one.
- Test the same request again after a short delay.
- Note the exact time when the failure happened.
- Save the request ID if the API gives you one.
- See whether the same error happens from another device or server.
If the same request starts working later without any change on your side, that points more toward a temporary upstream problem. It still isn’t proof, but it gives you a much better direction.
3. Test the Request Without Streaming
One of the most useful tests is to send the same type of request without streaming, if the API supports both modes. Instead of receiving small response chunks over time, your application waits until the server has a complete response and gets it in one piece.
If the non-streaming request works while streaming keeps failing, focus on the parts that only matter during a long-lived connection. That includes idle timeout settings, response buffering, proxies, VPNs, stream parsers, and gateway limits.
If both streaming and non-streaming requests fail, the problem may be broader. Check the request itself, authentication, server health, network connection, rate limits, and provider status before spending too much time on streaming code.
4. Check Your Internet Connection, VPN, and Proxy
Streaming needs a connection to stay alive while new chunks are arriving. Even a short interruption can break that connection. This is why an internet connection that seems fine for normal browsing can still cause problems with a long API stream.
A few simple tests can tell you a lot:
- Try the same request on another stable network.
- If you’re using Wi-Fi, test a wired connection if possible.
- Temporarily disconnect your VPN, where allowed, and retry.
- Check whether your system or company network uses a proxy.
- Test from another computer or server.
- Review firewall rules if API traffic passes through a controlled network.
If the API works without the VPN but fails when the VPN is active, don’t immediately assume the VPN software itself is broken. The route, proxy rules, connection limits, or idle timeout used by that network may be the real cause.
5. Increase the Correct Client Timeout
This is where people often change the wrong setting. An API client can have more than one timeout, and increasing the connection timeout won’t help much if the error is happening after the connection is already open.
Here are the main ones:
| Timeout | What It Controls |
|---|---|
| Connection timeout | How long the client waits to connect to the server |
| Read or idle timeout | How long it waits for new response data |
| Total request timeout | Maximum time allowed for the whole request |
For a stream idle timeout, the read or idle timeout is usually the setting worth checking first. The exact name depends on your SDK, HTTP library, programming language, or platform.
Don’t simply set the timeout to unlimited. A very large timeout can leave broken connections hanging around much longer than needed. Set a value that makes sense for the kind of response you’re expecting, then test again.
6. Reduce the Request or Expected Response Size
Long requests have more chances to run into trouble. A large prompt, huge payload, uploaded file, high output limit, or long generated response can keep the connection open much longer than a small request.
Try a smaller version of the same request. Reduce the input, ask for a shorter result, or lower the output limit temporarily. If a smaller request finishes normally while long ones keep timing out, you’ve learned something useful.
That doesn’t mean large requests are automatically bad. The test is mainly there to narrow down the problem. Longer processing can expose a short idle timeout or another limit that smaller requests never reach.
7. Reduce Concurrent Requests and Add Proper Retry Backoff
If your app sends many streaming requests at once, both your side and the API provider may have more connections to manage. Too much concurrency can lead to slower responses, connection pressure, rate limits, or streams that fail under load.
Try lowering the number of requests running at the same time. For retries, don’t immediately fire the request again over and over.
A better retry setup normally includes:
- A small delay before retrying.
- A longer delay after repeated failures.
- A maximum retry count.
- Support for Retry-After when the API provides it.
- Separate handling for rate-limit errors and network errors.
Exponential backoff is often used for this because the wait gets longer after each failure. The goal isn’t to make requests slower. It’s to stop temporary API problems from turning into a flood of repeated requests.
8. Update the API SDK or HTTP Client
An outdated SDK or HTTP library can sometimes be part of the problem, especially when streaming support has changed between versions. There may also be fixes for dropped connections, event parsing, HTTP/2 behavior, or timeout handling.
Check which SDK version your project is using. Compare it with the versions supported by the API provider and review what changed before updating. If you’re several versions behind, testing a newer supported release is worth doing.
Don’t update every dependency blindly just because you saw a timeout. Change one thing at a time when possible. That makes it easier to know what fixed the problem, and it also reduces the chance of introducing a new issue.
9. Check Your Application’s Stream Handling
The connection itself may be fine while your own code fails during the stream. This can happen when the application stops consuming response chunks, throws an error while parsing an event, aborts the request early, or treats incomplete streamed JSON as a finished response.
Check your application logs at the exact time the timeout occurs. Look for parser errors, cancelled requests, abort signals, closed sockets, exceptions inside callbacks, or code that exits the stream loop too early. If you’re building structured output from several chunks, make sure you don’t try to parse the final object before all required data has arrived.
This is especially important when the API works in a simple test client but fails inside your full application. In that case, your middleware, framework, parser, or stream handling code becomes a much stronger suspect.
10. Check Reverse Proxy, Gateway, or Load Balancer Timeouts
If your application sends API traffic through another server, the client timeout may not be the timeout that matters. A reverse proxy such as Nginx, an API gateway, CDN, load balancer, or serverless platform can close the connection first.
A common setup looks something like this:
Client → Your Server → Proxy or Gateway → API Provider
The upstream API might still be working, but if the middle layer decides the connection has been idle for too long, your client receives an incomplete response.
Check settings related to:
- Read or upstream timeout.
- Idle connection timeout.
- Gateway request limits.
- Load balancer connection limits.
- Serverless execution limits.
- Maximum request duration.
The names differ between platforms, so don’t copy one timeout value from a random configuration and assume it fits your setup. Find which layer is ending the connection first.
11. Check Proxy Buffering and Streaming Configuration
Streaming works best when each chunk can move through your system as it arrives. A proxy that buffers responses may collect data before forwarding it to the client. That can make the connection appear inactive from the client’s point of view even though the upstream API is still generating data.
If you’re using Server-Sent Events, chunked HTTP responses, or another streaming setup, check how your proxy handles response buffering. Compression and middleware can also affect when data gets flushed to the client.
Things worth checking include response buffering, streaming headers, compression behavior, and whether the platform fully supports long-lived responses. Don’t disable buffering across your whole server without understanding what else depends on it. Change only the route or service that needs streaming when possible.
12. Check Server Logs, Request IDs, and Resource Usage
At this point, logs become much more useful than guessing. Find the failed request’s timestamp and check what happened on your server around that moment.
Look for:
- Worker restarts.
- Process crashes.
- Out-of-memory errors.
- Upstream connection closures.
- CPU or memory spikes.
- Container restarts.
- Gateway errors.
- Request cancellation messages.
- Disk problems if the app writes temporary files or logs.
Keep the request ID too, if one is available. It can help you match client errors with server logs or give support staff something specific to search for.
Storage is worth checking only when there is a reason to suspect it. A normal API streaming timeout is not usually fixed by simply freeing disk space. But a server that cannot write temporary data or logs may fail in other ways that interrupt requests.
13. Handle Partial Responses Safely in Your Application
A partial response should not automatically be treated as a completed response. Your application needs a clear way to tell whether the stream ended normally or failed halfway through.
This matters even more with structured data. An incomplete JSON object may look close to valid but still be missing fields or closing characters. Validate the output before saving it, sending it to another service, or using it for an automated action.
Your app should decide what to do when a partial response arrives:
- Show the partial text with a clear error state.
- Discard it and retry.
- Save it for debugging.
- Ask the user to retry manually.
- Resume only if the API supports a safe continuation method.
Be careful with retries when requests have side effects. A text generation request is very different from a payment, account change, file deletion, or other transactional API call. Running those twice can create a much bigger problem than a timeout.
14. Reproduce the Request With a Minimal Client
When a full application has many layers, it can be hard to tell where the stream breaks. A minimal test removes most of those layers and gives you a cleaner answer.
Use a basic HTTP client, cURL, or the provider’s simplest supported SDK example. Send a small version of the same request directly to the API.
Then compare what happens:
- Use the same endpoint where possible.
- Keep the request body small.
- Test streaming first.
- Try non-streaming too.
- Compare the result with your main application.
If the minimal request works but your application fails, the problem is likely somewhere inside your code, middleware, proxy, or hosting setup. If the minimal request also times out, look more closely at the network, API provider, or client configuration.
One small thing here, never paste a real API key into screenshots, public bug reports, or shared terminal logs. Redact it before sharing anything.
How to Tell Whether the Timeout Is Client-Side or Server-Side?
It isn’t always possible to know from one failed request. Still, a few patterns can point you in the right direction.
| Signal | More Likely Client or Network | More Likely Server or Provider |
|---|---|---|
| Fails only on one computer | Yes | Less likely |
| Works after changing networks | Yes | Less likely |
| Works when VPN is disabled | Yes | Less likely |
| Local logs show client timeout | Yes | Less likely |
| Multiple users fail at the same time | Less likely | Yes |
| Same error appears from several networks | Less likely | More likely |
| Provider reports an incident | No | Yes |
| Request fails only through your proxy | Proxy/infrastructure | Not necessarily |
| Retry later works with no local changes | Possible | Possible |
Don’t use this table as absolute proof. Networks, proxies, API providers, and application servers can all create similar symptoms. Think of it as a way to decide what to test next.
What If the Error Happens Only on Long API Responses?
If short responses work and long ones fail, timing becomes a much stronger clue. Your request may be reaching an idle timeout, total request limit, gateway limit, or another connection limit that short requests never hit.
Try reducing the response length once and compare the result. If the short version works every time, check your client read timeout and any proxy or gateway timeout between the client and API. You should also review how often chunks arrive during long generations. A connection can still be open while one part of the system decides it has been idle for too long.
What If Retrying Always Fixes the Error?
If the second attempt nearly always works, the failure may be temporary. It could be a short network interruption, a slow backend worker, provider load, or another issue that disappears by the time you retry.
Still, don’t use “just retry it” as the permanent fix. Add controlled retry logic, record how often the timeout happens, and keep request timestamps or IDs. If the error starts happening more often, you’ll have useful data instead of only knowing that the second try worked.
Can a VPN Cause Stream Idle Timeout Errors?
Yes, a VPN can be involved. Streaming connections may travel through extra network routes, VPN servers, firewalls, or proxies. Any of those layers can reset a connection or apply an idle timeout.
A simple test is to repeat the same request without the VPN, where you’re allowed to do so. If it works reliably without the VPN and fails with it, investigate the VPN route or its connection rules. Don’t assume every VPN is a problem, though. Many work perfectly fine with streaming APIs.
Does Clearing Cache Fix a Stream Idle Timeout?
Usually, no. A stream idle timeout is normally related to the active API connection, network, client settings, server, or an intermediary such as a proxy. Clearing a browser cache does not normally change how a live API stream behaves.
There are exceptions if a specific application stores broken session data or network settings locally, but that’s more of an app-specific problem. For this error, spend your time checking timeout settings, streaming behavior, VPNs, proxies, and server logs before doing generic cache-clearing steps.
When Should You Contact the API Provider?
Contact the API provider when you’ve ruled out the easier local causes and can reproduce the error under clean conditions. Support will be much more useful if you give them details they can search for instead of only saying the API timed out.
Try to include:
- The exact error message.
- The date and time of the failure, including timezone.
- Request ID, if available.
- API endpoint or feature being used.
- SDK and version.
- Whether streaming and non-streaming both fail.
- Approximate request or response size.
- Whether the issue happens on another network.
- Sanitized logs around the failure.
Never send your secret API key in a support post, screenshot, or public issue. If support needs account details, follow the provider’s official secure process.
How to Prevent Stream Idle Timeout Errors?
Once the immediate problem is fixed, it’s worth making the application a little more tolerant of temporary stream failures. Streaming connections can fail even in a well-built system, so your app should expect the possibility instead of assuming every connection will stay perfect.
A few good habits help:
- Set reasonable read and idle timeout values.
- Use limited retries with backoff.
- Avoid unnecessary request concurrency.
- Monitor failed and incomplete streams.
- Keep SDKs on supported versions.
- Test long requests before pushing them to production.
- Check proxy and gateway limits when using streaming.
- Handle partial responses separately from completed ones.
- Keep useful request IDs and timestamps in your logs.
- Validate structured output before using it elsewhere.
You don’t need every protection on day one. Start with the parts that match your setup, especially timeout handling, retries, logging, and proper stream completion checks.
Final Thoughts
The API error: stream idle timeout – partial response received means the stream began but didn’t finish cleanly. The fastest troubleshooting path is usually to retry once, check provider status and your network, compare streaming with non-streaming, then inspect the client timeout. If the issue continues, move into application code, proxies, gateways, and server logs.
The main thing to remember is that a partial response tells you the API connection worked for at least part of the request. It doesn’t tell you which layer ended it. Finding that layer is what fixes the problem for good.
If you’re still getting the error, comment with where you’re seeing it, such as Python, Node.js, an AI API, cURL, or a specific app, and whether the response stops at roughly the same point each time.