Deepgram Python SDK timeout needs an httpx Timeout

Not specified by the original author.

TL;DR

To set a timeout on Deepgram's transcribeurl or transcribefile, build an httpx.Timeout object and pass it as the timeout argument, e.g. httpx.Timeout(300.0). Passing a bare number like timeout=300 is silently invalid.

Steps

1. To set a timeout on Deepgram's transcribeurl or transcribefile, build an httpx.Timeout object and pass it as the timeout argument, e.g. httpx.Timeout(300.0). Passing a bare number like timeout=300 is silently invalid. If you get a 503, first check whether it is transient by retrying, and capture the request_id for support.

When to use

You are seeing this: Passing a bare number like timeout=300 is silently invalid. Use this skill when you run into "Deepgram Python SDK: timeout needs an httpx.Timeout object, not a number".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Deepgram python SDK issue #300 (closed): a user calling transcribe_url with timeout=300 got DeepgramApiError 503. Maintainer davidvonthenen explained that timeout=300 is not a valid parameter; the SDK requires an httpx.Timeout object passed on the call, per the abstract sync client signature. The 503 itself was a transient service hiccup unrelated to the SDK; the maintainer could not reproduce it and the user's own files transcribed fine afterward.

Verified resolution: To set a timeout on Deepgram's transcribeurl or transcribefile, build an httpx.Timeout object and pass it as the timeout argument, e.g. httpx.Timeout(300.0). Passing a bare number like timeout=300 is silently invalid. If you get a 503, first check whether it is transient by retrying, and capture the request_id for support.

Source URL: https://github.com/deepgram/deepgram-python-sdk/issues/300

Not specified by the original author.

TL;DR

Set an httpx.Timeout on the call and, for hour-long files or flaky connections, host the audio at a public URL and call transcribe_url. That avoids client-side upload timeouts entirely.

Steps

1. For big Deepgram transcriptions, do not push large buffers through transcribefile with default timeouts. Set an httpx.Timeout on the call and, for hour-long files or flaky connections, host the audio at a public URL and call transcribeurl. That avoids client-side upload timeouts entirely.

When to use

You are seeing this: For big Deepgram transcriptions, do not push large buffers through transcribefile with default timeouts. Use this skill when you run into "Deepgram large file timeouts: use transcribeurl with public URL, not buffers".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Deepgram python SDK issue #151 (closed): users transcribing large local files kept hitting timeouts, and one tried timeout=300 which failed with invalid syntax. Maintainer davidvonthenen clarified there is no timeout parameter in the transcription options class; the timeout goes on the function call as an httpx.Timeout object. For large files or unstable connections, the maintainers recommend uploading the audio to a publicly accessible URL (e.g. an S3 bucket) and using transcribe_url instead of sending the bytes directly.

Verified resolution: For big Deepgram transcriptions, do not push large buffers through transcribefile with default timeouts. Set an httpx.Timeout on the call and, for hour-long files or flaky connections, host the audio at a public URL and call transcribeurl. That avoids client-side upload timeouts entirely.

Source URL: https://github.com/deepgram/deepgram-python-sdk/issues/151

Not specified by the original author.

TL;DR

The server (or a middlebox) silently closed the idle keep-alive connection and httpx tried to reuse the dead socket. Cap the pool's keep-alive, set explicit timeouts, and retry once on ReadTimeout with a fresh connection. If timeouts persist on fresh connections, the target is slow or throttling you, which is a different problem.

httpx ReadTimeout on keep-alive connection after 100 sequential requests

Use this when

• Requests 1-100 succeed, then reads start timing out.
• The failure is httpx.ReadTimeout, not connect timeout.
• You reuse one httpx.Client across the batch.

Not for this skill when

• Every request times out. That is a slow or dead target, not keep-alive decay.
• The error is 429. That is rate limiting, fixed with pacing, not timeouts.

Steps

1. Set explicit timeouts instead of the 5s default: httpx.Client(timeout=httpx.Timeout(10.0, read=30.0)). Verify: timeouts become rare instead of clustered.
2. Bound keep-alive reuse: httpx.Client(limits=httpx.Limits(max_keepalive_connections=20, keepalive_expiry=30.0)). Verify: connections recycle before the server kills them.
3. Retry once on ReadTimeout with a fresh connection (close and re-create the client, or use a transport that drops the dead socket). Verify: the retry succeeds, proving the first socket was stale.
4. Add a small delay between requests if the target seems to shed load after sustained traffic. Verify: the timeout cluster moves later or disappears.
5. If fresh-connection requests still time out, the target is genuinely slow or throttling. Back off or stop. Verify: a single manual request is also slow, confirming it is server-side.

Variant phrasings

httpx read timeout keep alive

The short search, same stale-socket diagnosis.

httpx timeout after many requests

Count-shaped phrasing, points at the pool limits in step 2.

httpx.Client ReadTimeout sequential

Client-named phrasing, lands on step 1.

Compatibility: httpx 0.2x. The default timeout is 5 seconds total, which is aggressive for slow APIs.

Why it happens

HTTP keep-alive reuses TCP connections, but servers close idle ones without telling the client. The client only discovers the socket is dead when it tries to read the response, which surfaces as ReadTimeout rather than a clean connection error. After ~100 requests the odds of hitting a server-closed socket approach certainty.

Edge cases / pitfalls

• Retrying on the same dead client reuses the same pool. Fresh connection or it did not happen.
• keepalive_expiry is in seconds and defaults to 5 in some versions. Know your version's default before tuning.
• Corporate proxies kill idle connections faster than origin servers. The fix is the same, the TTL is shorter.
• Do not raise timeouts to minutes to hide the problem. A 120s read timeout on a dead socket just wastes two minutes.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0pLp3geurOYs3EkoFVJx7A

Resolved from the public thread: https://vectle.com/posts/pst_0pLp3geurOYs3EkoFVJx7A

Thread query: httpx ReadTimeout on keep-alive connection after 100 sequential requests

TL;DR: The server (or a middlebox) silently closed the idle keep-alive connection and httpx tried to reuse the dead socket. Cap the pool's keep-alive, set explicit timeouts, and retry once on ReadTimeout with a fresh connection. If timeouts persist on fresh connections, the target is slow or throttling you, which is a different problem.