Codice di stato 499: cosa intende nginx per client closed request

Cosa significa il codice di stato 499

499 Client Closed Request è specifico di nginx e non è mai definito in alcuna RFC. I codici sopra 99 e sotto 600 sono riservati in generale alle status line HTTP, ma 499 è una convenzione propria di nginx, registrata quando nginx rileva che la connessione del client è caduta mentre stava ancora aspettando che l'applicazione upstream rispondesse, o mentre stava ancora inviando indietro il corpo della risposta al client. La forma più comune nel mondo reale è un upstream lento combinato con un client, una scheda del browser, o un load balancer il cui proprio timeout è più breve di quanto il server avrebbe impiegato, così il client riaggancia per primo.

Come appare nei log

Non vedrai mai 499 come codice di stato restituito a un client, un browser, curl, o altro, perché per definizione il client è già andato via nel momento in cui nginx glielo avrebbe inviato. Esiste solo nel log di accesso proprio di nginx:

10.0.0.12 - - [19/Sep/2026:14:02:11 +0000] "GET /api/report HTTP/1.1" 499 0 "-" "python-requests/2.31"

La dimensione della risposta di 0 byte e la tempistica relativa al tempo di risposta noto del tuo upstream sono i due dettagli più utili: un 499 che atterra costantemente proprio intorno al timeout del tuo upstream, senza nulla inviato indietro, indica chiaramente "il backend era troppo lento e qualcosa ha rinunciato ad aspettare."

Cosa causa un 499

• Un'applicazione upstream lenta. Il backend impiega più tempo a rispondere di quanto un client o un intermediario sia disposto ad aspettare, sia che si tratti di una query di database lenta, una chiamata API esterna, o un calcolo genuinamente pesante.
• Un timeout lato client più breve di quanto il server richieda. Una scheda del browser chiusa, un'app mobile che rinuncia a una connessione instabile, o il timeout proprio di una libreria client HTTP che scatta prima che arrivi la risposta.
• Un load balancer o proxy upstream che va in timeout per primo. Se qualcosa si trova tra l'utente finale reale e nginx, il suo proprio timeout può innescare una disconnessione che nginx registra come 499, anche se l'utente finale reale non ha mai esplicitamente annullato nulla.
• Un utente che naviga altrove o ricarica. Qualcuno che si allontana da una pagina a caricamento lento, o che preme ricarica con impazienza, chiude la connessione in corso prima che nginx avesse finito.
• Valori di timeout incoerenti lungo la catena. Un client, una CDN, un load balancer, e nginx stesso possono avere ciascuno un timeout diverso, e quello più breve determina quando avviene la disconnessione, indipendentemente da come sono configurati gli altri.

Perché non compare mai in un browser

499 non è una risposta, è una nota che nginx fa a se stesso su una risposta che non ha mai finito di inviare. Un utente la cui scheda ha prodotto un 499 nei tuoi log non vede assolutamente nulla: nessuna pagina di errore, nessun codice di stato, solo una pagina che ha smesso di caricarsi o uno spinner che non si è mai risolto, perché non c'era alcuna risposta che il browser potesse visualizzare. Questo è esattamente il motivo per cui affidarsi agli errori segnalati dagli utenti li manca completamente; l'unico posto in cui un 499 è visibile è il log di accesso stesso del server.

Come correggere e ridurre i 499

Non esiste un'unica impostazione che elimina i 499, dato che la causa sottostante è una gara tra il client che rinuncia e il server che finisce, e la correzione dipende da quale lato di quella gara sia effettivamente rotto. Inizia stabilendo se l'upstream è costantemente lento per la rotta interessata, o se le disconnessioni si raggruppano intorno a un client, una rete, o un intermediario, dato che questi indicano correzioni diverse.

1. Indaga prima il tempo di risposta dell'upstream, dato che un backend lento è la causa sottostante più comune. Guarda quanto tempo le richieste interessate hanno effettivamente impiegato a livello upstream, non solo che nginx ha registrato un 499.
2. Allinea i valori di timeout lungo l'intera catena, deliberatamente, invece di lasciare il valore predefinito di ogni livello: client, CDN, load balancer, e i proxy_read_timeout e proxy_connect_timeout propri di nginx dovrebbero essere impostati con una chiara comprensione di quale sia destinato a scattare per primo.
3. Considera proxy_ignore_client_abort se far finire all'upstream il proprio lavoro anche dopo che il client si è disconnesso conta per la tua applicazione, per esempio per completare una scrittura che non dovrebbe restare a metà:

   proxy_ignore_client_abort on;

   Questo non impedisce la voce di log 499 per la disconnessione originale; cambia se nginx mantiene in esecuzione la richiesta upstream indipendentemente.
4. Velocizza il lavoro upstream effettivo dove la causa radice è davvero un endpoint lento, dato che nessuna quantità di regolazione dei timeout corregge un backend che di per sé impiega troppo tempo; profila le query o le chiamate lente specifiche dietro la rotta interessata.
5. Tratta un tasso crescente di 499 come un segnale reale, non rumore di log da filtrare via, dato che di solito significa o che la tua applicazione è diventata più lenta o che la tua configurazione dei timeout è disallineata da qualche parte nella catena.

Come prevenire che diventi un'interruzione

Dato che il 499 non raggiunge mai il client come errore visibile, è facile che un endpoint davvero lento passi inosservato finché qualcuno non legge i log di accesso, anche mentre gli utenti reali stanno silenziosamente abbandonando le richieste. Un controllo HTTP pianificato misura il tempo di risposta effettivo contro l'endpoint direttamente e avvisa quando degrada, cogliendo il rallentamento che sta producendo i 499 prima che cresca fino a richieste che falliscono del tutto. Il monitoraggio da più postazioni aiuta anche a distinguere un backend davvero lento da un timeout che scatta solo per client su un particolare percorso di rete.

Errori correlati

Vedi 504 Gateway Timeout per l'equivalente standard e visibile al client quando è nginx stesso a rinunciare ad aspettare l'upstream invece che il client a rinunciare per primo, la panoramica 4xx per la famiglia standard di errori client, e 429 Too Many Requests per un tipo diverso di rifiuto legato alla frequenza piuttosto che alla tempistica.

Domande frequenti

Il 499 è un vero codice di stato HTTP?

No. È la convenzione di log propria di nginx per un client che si è disconnesso prima che la risposta finisse, e non viene mai inviato sul filo a nessun client dato che il client è già andato via nel momento in cui verrebbe inviato.

Perché il mio strumento di monitoraggio non vede mai un 499?

Un controllo di monitoraggio è esso stesso un client, e se è lui a rinunciare a una risposta lenta, segnalerà il proprio errore di timeout, non 499, dato che non riceve mai una risposta HTTP da cui leggere un codice di stato. Il 499 compare solo nella voce di log di accesso propria del server per quella richiesta.

Un 499 significa che il mio server è andato in crash?

No. Significa specificamente che il server stava ancora lavorando, o stava per iniziare a lavorare, quando il client si è disconnesso. Un crash tipicamente produrrebbe invece un 502 o 500, una volta che qualcosa ha effettivamente risposto.

Posso fermare l'elaborazione upstream quando un client si disconnette?

Per impostazione predefinita nginx generalmente smetterà di aspettare l'upstream una volta che il client se n'è andato, ma il comportamento esatto dipende dalle tue impostazioni proxy; proxy_ignore_client_abort on dice a nginx di lasciare che la richiesta upstream continui invece di abbandonarla.

Qual è la correzione più comune per 499 frequenti?

Allineare i valori di timeout tra il client, qualunque proxy o load balancer intermedio, e nginx stesso, combinato con l'affrontare qualunque cosa stia rendendo lento l'upstream fin dall'inizio. Nessuno dei due da solo di solito risolve un pattern persistente.