Request Timeout

Description

Examples

POST /api/upload HTTP/1.1
Host: api.example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary
Content-Length: 52428800
Authorization: Bearer token123

------WebKitFormBoundary
[... client stalls here, body never completes ...]

HTTP/1.1 408 Request Timeout
Content-Type: application/json
Connection: close

{"error": "request_timeout", "message": "The server did not receive a complete request within the allotted time. Please retry.", "timeout_seconds": 60}

GET /api/status HTTP/1.1
Host: api.example.com
Connection: keep-alive

[... connection sits idle for 120 seconds ...]

HTTP/1.1 408 Request Timeout
Connection: close
Content-Length: 0

GET /api/data HTTP/1.1

Host: api.example.com

[... 1 byte every 30 seconds ...]
Accept: application/json

[... server timeout reached before headers complete ...]

HTTP/1.1 408 Request Timeout
Content-Type: application/json
Connection: close
Retry-After: 30

{"error": "request_timeout", "message": "Request headers were not received within 60 seconds.", "retry_after": 30, "documentation_url": "https://api.example.com/docs/timeouts"}

Edge Cases

• •408 is a SERVER-side decision about CLIENT speed — not about server processing time. If the server received the full request but took too long to process it, that's not a 408 situation (no standard code exists for that; some use 503 or 504 behind a proxy).
• •Browsers often never display 408 because the TCP connection drops before the response can be delivered. The client may see a network error or ERR_CONNECTION_RESET instead of a clean 408 response.
• •Nginx uses 408 for client_header_timeout and client_body_timeout violations. If a client sends headers within the limit but then stalls on the body, Nginx returns 408 after client_body_timeout expires — even if some body bytes were received.
• •Some servers (notably Nginx) send 408 on idle keep-alive connections to reclaim resources. This is technically valid but can trigger retry storms if clients treat every 408 as 'retry immediately'. Implement exponential backoff.
• •The Slowloris attack exploits this exact mechanism — sending partial headers very slowly to keep connections open. Servers defend with aggressive client_header_timeout values and connection limits per IP. Apache's mod_reqtimeout was created specifically for this.
• •408 should include Connection: close because the request was never completed — there's no clean way to continue on the same connection. The server doesn't know where the next request boundary would be in the byte stream.
• •Cloudflare returns 408 after 100 seconds of connection idle time, but this is measured at the edge — the origin server's own timeout may be different. Clients behind Cloudflare see Cloudflare's timeout, not the origin's.
• •Unlike 401 or 403, a 408 explicitly means the client can retry without modification. The request content isn't wrong — it just didn't arrive in time. Retry with the same headers, same body, same everything.

When You'll See This

• →Mobile client on a flaky cellular connection loses signal mid-upload
• →Large file upload stalls because the client's upstream bandwidth is saturated
• →Slowloris-style attack sending partial HTTP headers at 1 byte per second
• →Keep-alive connection sitting idle beyond the server's configured timeout
• →Client opens connection and sends headers but crashes before sending the body
• →Load balancer health check connection that opens but never sends a request
• →WebSocket upgrade request that never completes the handshake within the timeout window
• →API client with a misconfigured Content-Length that promises more bytes than it sends

Implementation References

History

Introduced in HTTP/1.1 (RFC 2068, January 1997) alongside the persistent connection model that made idle-connection timeouts necessary. Carried forward unchanged through RFC 2616 (1999) and RFC 7231 (2014). Refined in RFC 9110 (June 2022) with clearer language that the server MAY close the connection without waiting for the request to complete. Became operationally significant with the Slowloris attack disclosure (2009) which exploited slow-header transmission to exhaust server connections.

Related Status Codes

Related Headers

FAQ