Fix API Error: Stream Idle Timeout – Partial Response Received

The API error: stream idle timeout – partial response received means the request started, but the stream stopped sending new data before the full response arrived. Your app received part of the output, waited too long for the next chunk, then closed the connection.

Start with three quick checks. Retry the request once, test the same request without streaming, and try a smaller input. If the error returns after nearly the same number of seconds each time, a client, proxy, gateway, or server timeout is probably involved.

What Does “Stream Idle Timeout – Partial Response Received” Mean?

A streaming API sends a response in small pieces called chunks. Your app receives one chunk, waits for the next, and continues until the API sends a proper completion signal.

A stream idle timeout happens when no new chunk arrives for too long. The request may still be running on the server, but one part of the connection path stops waiting. The message “partial response received” means some data arrived before the stream ended.

That partial response may contain unfinished text, broken JSON, missing tool output, or an incomplete result. Do not treat it as successful unless your app receives the expected final event, a normal stream close, or a complete response object.

The exact timeout name and setting depend on the API provider, SDK, HTTP client, proxy, and hosting platform you use.

Common Reasons of API Error in Claude

The most common cause is a timeout that is shorter than the gap between response chunks. Large requests, slow model output, unstable internet, proxy buffering, or an overloaded server can create the same problem.

Common causes include:

• The client read timeout is too low.
• The API takes too long to send the next chunk.
• The prompt, payload, or response is too large.
• A VPN, proxy, firewall, or weak connection resets the stream.
• The API provider is slow or having a temporary issue.
• Nginx, a CDN, or a load balancer closes idle connections.
• Response buffering holds chunks instead of sending them.
• An old SDK handles streaming or timeouts badly.
• The server runs out of workers, memory, or connections.
• A long tool call or backend task creates a quiet gap.
• A serverless platform reaches a hard request limit.

A few patterns can help narrow it down. If the error happens once, it may be temporary. If it always happens after the same number of seconds, look for a fixed timeout. If short responses work but long ones fail, request size or processing time is more likely.

Quick Diagnosis Before You Change Anything

Use the same request for every test. Keep the endpoint, model, payload, and output limit unchanged so the results are easy to compare.

Record the request ID, start time, failure time, endpoint, SDK version, and the last chunk received. These details make later checks much easier.

How to Fix API Error: Stream Idle Timeout – Partial Response Received?

Work through the fixes in order. Test the same request after each change and avoid editing several settings at once. That way, you’ll know which fix solved the issue.

1. Retry the Request Once

Send the same request again. A short network drop, overloaded worker, or temporary provider slowdown can cause one stream to fail while the next completes normally.

The retry result gives you a useful clue:

• If the second request works, the failure may have been temporary.
• If it fails after the same number of seconds, check for a fixed timeout.
• If it fails at a different point, network or provider instability is more likely.

Do not keep retrying without a limit. Repeated attempts can increase API costs and server load. Requests that create payments, messages, or database records also need protection against duplicate actions.

2. Check the API Provider’s Service Status

The provider may be slow, overloaded, or having trouble with one endpoint, model, or region. Streaming can begin normally and then pause long enough for your client to close the connection.

Check the provider’s status page, dashboard alerts, and recent incidents. Where available, test another endpoint, region, or model. If one service works while another keeps failing, the problem may not be inside your app.

A green status page does not rule out every provider issue. Small or regional problems may appear later. Keep the request ID and exact failure time if you need to contact support.

3. Test the Same Request Without Streaming

Turn streaming off and send the same request as a normal API call. The client will wait for the full response instead of receiving it piece by piece.

If the non-streaming request works, the API can probably complete the job. Focus on stream parsing, idle timeout settings, buffering, or an intermediary proxy.

If both streaming and non-streaming fail, the issue is probably wider. The request may be too large, the endpoint may be slow, or a server or platform limit may be ending it.

Non-streaming mode can also work as a temporary fallback. Keep in mind that large responses may use more memory because the full body is held before your app receives it.

4. Reduce the Request or Response Size

Large requests often take longer to process. A big payload, long conversation, large file, high record count, or very long requested output can create long gaps in the stream.

Try a smaller test first:

• Shorten the prompt or payload.
• Remove old conversation messages.
• Lower the maximum output size.
• Request fewer records.
• Reduce the batch size.
• Remove unneeded response fields.
• Disable tools or functions that are not required.
• Split large files or logs into smaller parts.

Change one item at a time. If the smaller request works, the problem is likely tied to request size, response size, or slow processing rather than a broken connection.

5. Increase the Client Read or Idle Timeout

The client may be stopping before the API sends the next chunk. Look for a setting named read timeout, response timeout, stream timeout, socket timeout, idle timeout, or request timeout.

The exact setting depends on your SDK and HTTP client. Some libraries use separate limits for connecting, reading, writing, and waiting for a connection from a pool.

Use this process:

• Note how many seconds pass before the error.
• Find the relevant read or idle timeout.
• Raise it above the normal gap between chunks.
• Test short and long requests.
• Keep a reasonable upper limit.

Do not remove timeouts completely. A dead connection should still close after a sensible period.

Also check the HTTP library under the SDK. The SDK may allow a longer request while the lower-level client still ends the stream earlier.

6. Check the Internet Connection, VPN, Proxy, and Firewall

Streaming connections can fail even when websites load normally. A stream stays open for longer, so a brief network reset may end it.

Test in this order:

• Try another Wi-Fi network or a wired connection.
• Test with a mobile hotspot.
• Turn off the VPN for one controlled test.
• Bypass the local proxy.
• Check firewall logs for resets or blocked connections.
• Test whether antivirus HTTPS inspection is interfering.

If the request works on another network, your application may be fine. The problem is more likely inside the VPN, firewall, proxy, ISP route, or local network.

Do not leave security tools disabled. Use the test only to find the cause, then change the correct rule or setting.

7. Update the API SDK and HTTP Client

An older SDK may contain bugs in stream parsing, timeout handling, connection reuse, or final event processing. This fix is more likely when the error appears in one library but not in a direct cURL test.

Record your current versions first. Then check release notes for fixes related to streaming, timeouts, dropped connections, or retries.

Update carefully:

• Test the update outside production.
• Update the API SDK.
• Update its direct HTTP dependency if needed.
• Review any changed timeout settings.
• Run the same failing request again.
• Keep the previous version ready for rollback.

Avoid updating every dependency at the same time. Too many changes make new problems harder to trace.

8. Review Reverse Proxy and Gateway Timeouts

If your app uses Nginx, Cloudflare, a load balancer, an API gateway, or Kubernetes ingress, that layer may close the stream before the backend finishes.

Compare the failure time with settings such as:

• Proxy read timeout
• Proxy send timeout
• Idle connection timeout
• Upstream response timeout
• Gateway request duration
• Load balancer idle timeout
• Serverless execution limit

A good test is to call the backend directly when it is safe to do so. If the direct request works but the public route fails, the proxy, CDN, gateway, or ingress is likely involved.

In many setups, the first applicable timeout reached anywhere in the request path ends the connection. Raising the timeout only inside the app may not help if another layer still has a lower limit.

9. Disable Buffering on the Streaming Route

A streaming endpoint should send chunks as they are created. If a proxy or framework holds those chunks in a buffer, the client sees no data and may report an idle timeout.

The easiest sign is this: the direct backend shows live chunks, but the public URL sends the whole response at once.

Check:

• Proxy buffering
• Response compression
• CDN caching
• Framework flush behavior
• Streaming content type
• Cache-control headers

Apply changes only to the streaming route. Turning buffering off across the entire site may affect normal traffic.

For Server-Sent Events, the response usually needs the correct event-stream content type. Other protocols have different requirements, so follow the rules for the stream type you use.

10. Check Server Resources, Workers, and Connections

An overloaded backend may keep the connection open without sending new data. The client waits, the stream stays quiet, and the idle timeout fires.

Start with the main checks:

• CPU usage
• Free memory
• Worker count and restarts
• Database connection pool
• HTTP connection pool
• Disk space
• Container CPU and memory limits

If those look normal, move to advanced checks such as file descriptors, event loop delay, thread pool use, temporary directories, and log volume size.

A full disk is easy to miss. The application may still answer small requests while large tasks fail when logs or temporary files need to be written.

Do not upgrade the server before you know what is blocked. A connection leak or poor worker setup can return on a larger machine.

11. Add Safe Retry Handling

Automatic retries can recover from temporary failures, but they need limits. Retrying at once, again and again, may add more load during an outage.

A safer retry flow is:

• Retry only errors that may be temporary.
• Wait before the next attempt.
• Increase the wait after each failure.
• Add a small random delay.
• Stop after a limited number of tries.
• Log the request ID and final error.

Waiting longer after each attempt is often called exponential backoff. The random delay helps stop many clients from retrying at the same moment.

For requests that create records or trigger actions, use an idempotency key when supported. This helps prevent the same action from happening twice.

Your app should also detect partial output. It can discard it, mark it as incomplete, or offer a clear retry option.

12. Split or Queue Very Long Requests

Some tasks are simply too long for one open streaming connection. In that case, raising the timeout again may only delay the next failure.

Split large work into smaller parts. Process documents by section, reduce batch size, or create a long response in stages. Smaller requests are easier to retry and easier to track.

For tasks that take several minutes, use a background job. The client sends the task, receives a job ID, and checks the result later. This works well for large reports, media processing, document analysis, exports, and long batch jobs.

If the same task keeps reaching platform or network limits, change the request flow instead of keeping one HTTP connection open longer.

When the API Provider Is Probably Responsible?

The provider is more likely to be at fault when the same request fails across different devices, networks, SDKs, and direct command-line tests.

Strong signs include:

• Direct requests fail without your proxy.
• Several users see the same error.
• Different networks fail in the same way.
• One endpoint, model, or region is much slower.
• Response times are far above normal.
• The provider reports an incident.
• Local timeout settings are already high enough.
• Other parts of your app work normally.

Before contacting support, collect the request ID, timestamp with timezone, endpoint, region, SDK version, and time before failure. Add a short sanitized log sample.

Do not share API keys, cookies, authorization headers, or private user data.

How to Prevent Stream Idle Timeout Errors?

Once the error is fixed, keep the full request path in mind. The client, proxy, server, and provider all need settings that make sense for the normal response time.

Use these habits:

• Set a realistic client read timeout.
• Keep proxy and gateway limits aligned.
• Measure the longest normal gap between chunks.
• Reduce very large requests and outputs.
• Keep SDKs and HTTP clients updated.
• Validate the final stream completion event.
• Add limited retries with a delay.
• Use idempotency for actions that must not repeat.
• Monitor CPU, memory, workers, and connection pools.
• Log request IDs and timeout details.
• Test the complete production route before release.
• Use smaller tasks or background jobs for long work.

Do not choose timeout values from one fast request. Test during normal and busy periods so the setting covers expected delays without leaving dead connections open forever.

It also helps to show users a clear error when a stream ends early. Mark the response as incomplete and offer a retry instead of showing broken output as finished.

Final Thoughts

The stream idle timeout – partial response received error usually means one part of the request path waited too long for new data. Start with a retry, non-streaming test, smaller request, and another network. These checks often reveal the cause quickly.

If the error keeps returning, compare the failure time with client, proxy, gateway, and server limits. Check buffering and backend resources as well. For very long tasks, splitting the work or using a background job is often the better fix.

Which step fixed the error for you, and did it always stop after the same number of seconds?