408

Request Timeout

4xx Client Error

Back to list.md

ELI5

You took too long to send your request. The server got tired of waiting and gave up.

Server perspective

Use 408 when the server times out waiting for the client to send a complete request.

When to use

•Return 408 for idle or stalled client connections where the request never completed in time
•Use it to close connections the server no longer wants to keep open
•Client sends request headers but body too slowly
•Long delays between request parts
•Client connection appears stalled
•Slow file uploads that timeout

How to respond

•Include Connection: close when closing the connection
•Tune timeout behavior so normal clients are not punished by overly aggressive limits

Headers to consider

•Connection

Response body

•A body is optional; keep it short because the server is usually closing an idle or incomplete request.

Server-side pitfalls

•Do not use 408 for slow upstream servers; that is a different problem from 504
•Do not confuse client send-timeouts with application processing failures
•Server processing timeout (use 500 Internal Server Error)
•Gateway/proxy timeout (use 504 Gateway Timeout)
•Rate limiting (use 429 Too Many Requests)

Examples

Slow file upload

Request:

POST https://api.example.test/upload

# Body
<streaming upload body>

Response:

408 Request Timeout

# Headers
Content-Type: application/json
Connection: close

# Body
{
  "error": "request_timeout"
}

Client took too long to send file data, server timed out

References

Related Status Codes

Gateway Timeout

I'm a middleman server, and the server I was trying to talk to took too long to respond, so I gave up waiting.