Set timeouts and buffering

Timeouts describe different stages of a proxied request, and Nginx lets you bound each stage separately. A single large value can hide a slow or stuck upstream for too long, so it pays to know which knob covers which phase.

location /api/ {
  proxy_pass http://127.0.0.1:3000;

  proxy_connect_timeout 5s;
  proxy_send_timeout    15s;
  proxy_read_timeout    30s;
  client_max_body_size  10m;
}

proxy_connect_timeout bounds how long Nginx waits to open the TCP connection to the upstream. A healthy local application connects in milliseconds, so 5 seconds is already generous — if connecting takes longer, the process is down or drowning, and waiting more won’t fix it.

proxy_read_timeout bounds the gap between two successive reads from the upstream while Nginx waits for the response. This is the one that fires when your application hangs on a slow query. When it expires, the client gets a 504 Gateway Time-out. proxy_send_timeout is the same idea in the other direction, for writing the request to the upstream.

client_max_body_size caps the request body. Anything larger is rejected with 413 Request Entity Too Large before it reaches the application. The default is only 1 megabyte, which is the classic reason file uploads fail behind a fresh Nginx.

Pick the values from measured behavior, not guesses. List one normal and one worst-case duration for the endpoint — say checkout takes 800ms normally and 12s at the p99 — then set the read timeout a little above the worst case, not at 300s “to be safe”. A generous timeout keeps a dead request occupying an upstream process long after the user gave up.

Test the failure response on purpose:

curl -i https://api.example.com/api/slow-report
# HTTP/1.1 504 Gateway Time-out     <- upstream exceeded proxy_read_timeout

curl -i -X POST https://api.example.com/api/upload --data-binary @big-video.mp4
# HTTP/1.1 413 Request Entity Too Large

Proxy buffering is the related setting people forget. With proxy_buffering on (the default), Nginx reads the upstream response quickly into memory and disk buffers, freeing the upstream to move on while Nginx trickles bytes to a slow client. Keep it on for normal responses. Turn it off per-location with proxy_buffering off; only for streaming endpoints where the client must see bytes as the upstream produces them — otherwise progress events sit in a buffer instead of reaching the browser.