Phase Timeouts and the Overall Proxy Request Deadline
Separate per-phase limits from the total time budget of a proxied operation, including retries and response consumption.
Connection and read timeouts limit particular waits. They do not necessarily cap an entire proxied operation, which can also include queuing, DNS, CONNECT, TLS, redirects, retries, and response consumption.
| Limit | Scope |
|---|---|
| Connect timeout | Connection setup under the client's definition |
| Read inactivity timeout | A wait without the expected data progress |
| Overall deadline | The complete operation's allowed duration |
Start with the operation's budget
Use the client's documented total deadline or cancellation mechanism where available, alongside phase limits. HTTPX separates pool, connect, read, and write waits. Requests states that its timeout is not a complete-download limit. curl provides a total-transfer timeout.
For example, a twenty-second job spends two seconds queuing, three establishing its route, and six on an unsuccessful exchange. Its next attempt has roughly nine seconds left. Giving every retry a fresh twenty seconds would discard the original budget.
Use a monotonic clock for elapsed-time accounting. Carry an absolute deadline or remaining duration through the layers owning the work. If a surrounding cancellation mechanism cannot enforce the required scope, make that limitation explicit.
Include the body and cleanup
A method returning after headers may leave body reading outside its deadline. Decide whether the budget covers establishment, a whole finite download, or a long-lived stream with separate liveness rules. A modern .NET headers-and-body cancellation example carries one token across both stages.
Leave time to close responses and complete cancellation before another attempt takes pool capacity. Record the failed stage and elapsed time; repeated reads making progress can satisfy inactivity limits while the overall job runs too long.
A gateway's upstream deadline belongs to that gateway. Once it returns 504, unused client budget cannot extend the completed attempt. Keep each timer attached to its owner when deciding which setting needs correction.