504 Gateway Timeout: trage backends en 502 vs 503 vs 504
Een 504 Gateway Timeout betekent dat een proxy uw backend bereikte, op een antwoord wachtte, en opgaf voordat er een aankwam. Niets crashte en niets weigerde het verzoek: iets achter de proxy is trager dan de proxy bereid is te wachten.
Wat een 504 meldt
RFC 9110 definieert 504 voor een server die optreedt als gateway of proxy en geen tijdig antwoord ontving van een upstream-server die hij moest benaderen. Het woord "tijdig" wordt bepaald door configuratie, niet door de specificatie, dus een 504 is altijd een uitspraak over twee dingen tegelijk: hoe traag de backend was, en op welke limiet de proxy was ingesteld.
Dat heeft een belangrijk praktisch gevolg. Wanneer een proxy 504 teruggeeft, blijft de backend meestal aan het verzoek werken. De verbinding met de client is weg, maar de trage query draait nog, het rapport wordt nog gegenereerd, en de resources blijven vastgehouden. Dat is waarom een golf van 504's een server vaak erger maakt: elk verlaten verzoek laat werk achter, en de wachtrij groeit sneller dan hij leegloopt.
504 versus 502 versus 503
| 502 Bad Gateway | 503 Service Unavailable | 504 Gateway Timeout | |
|---|---|---|---|
| Wat er gebeurde | Backend gaf een ongeldig antwoord of sloot de verbinding | Server weigerde het werk bewust | Backend accepteerde het werk en antwoordde nooit op tijd |
| Backendstatus | Down, crasht, of spreekt het verkeerde protocol | Up, maar overbelast of in onderhoud | Up en druk, nog aan het verwerken |
| Antwoordsnelheid | Meestal onmiddellijk | Meestal onmiddellijk | Traag, komt aan bij de time-outlimiet |
| Typische logregel | connect() failed of upstream prematurely closed connection | Onderhoudsregel, of geen gezonde upstreams | upstream timed out (110: Connection timed out) |
Retry-After | Niet gebruikelijk | Gebruikelijk en aanbevolen | Niet gebruikelijk |
| Eerste plek om te kijken | Draait het backendproces? | Capaciteit, onderhoudsvlaggen, health checks | Trage queries en trage afhankelijkheden |
In de praktijk faalt een 502 snel, weigert een 503 beleefd, en laat een 504 u eerst wachten. De speciale 502-handleiding en het 5xx-overzicht behandelen de andere twee volledig.
Waarom de backend te traag is
- Trage databasequery's. Een ontbrekende index, een query die met de data meegroeide, een N+1-patroon in een loop, of lockcontentie onder concurrency. De meest voorkomende oorzaak.
- Trage aanroepen van derden. Een uitgaand API-verzoek zonder eigen time-out erft de slechtste dag van de externe dienst en geeft die door aan uw bezoekers.
- Koude starts. Het eerste verzoek na een opschaling, een containerstart of een inactieve periode betaalt in één keer voor initialisatie, verbindingsopbouw en cache-opwarming.
- Werkelijk zwaar werk op een webverzoek. Rapportgeneratie, exports, beeldverwerking of bulkimports die synchroon worden afgehandeld, overschrijden uiteindelijk elke redelijke time-out.
- Resourcecontentie. CPU-verzadiging, geheugendruk en swapping maken elk verzoek trager, dus de traagste steken als eerste de limiet over.
- Te krap ingestelde time-outs. Heeft een endpoint legitiem langer nodig dan de proxy toestaat, dan is de configuratie de bug, niet de code.
- Netwerkproblemen tussen sprongen. Pakketverlies of vertragingen bij DNS-resolutie voor het upstream-adres voegen latency toe die niet in applicatietimings verschijnt.
Hoe u een 504 diagnosticeert en repareert
- Meet de tijd tot de fout. De vertraging voor een 504 komt meestal overeen met de geconfigureerde time-out, wat u vertelt welke sprong hem produceerde:
Een 504 op bijna precies 60 seconden wijst op een standaard proxy-leestime-out. Een op 30 of 100 seconden wijst op welk onderdeel dan ook met dat getal geconfigureerd, vaak een CDN in plaats van uw eigen proxy.curl -sS -o /dev/null -w "%{http_code} %{time_total}s\n" https://example.com/slow-page - Zoek uit of het één endpoint is of allemaal. Eén trage URL is een applicatieprobleem. Alles tegelijk traag is resourceverzadiging of een falende afhankelijkheid.
- Lees het foutenlog van de proxy. Bij nginx is de regel expliciet:
Ze noemt de upstream en de fase, wat een trage connect scheidt van een traag antwoord.[error] upstream timed out (110: Connection timed out) while reading response header from upstream, upstream: "http://127.0.0.1:8080/" - Tim de backend rechtstreeks, zonder de proxy. Duurt hetzelfde verzoek tegen de origin 90 seconden, dan meldt de proxy de waarheid en hoort de oplossing bij de applicatie.
- Profileer het trage pad. Controleer het log voor trage query's, dan applicatietraces. De meeste 504's herleiden tot één query of één uitgaande aanroep.
- Repareer de oorzaak vóór de time-out. Voeg de index toe, cache het dure resultaat, of verplaats werkelijk lang werk naar een achtergrondtaak die onmiddellijk antwoordt en voortgang apart meldt.
- Verhoog de time-out alleen wanneer het werk legitiem lang is, en verhoog hem consistent op elke sprong. Een CDN-limiet van 30 seconden maakt een origin-time-out van 120 seconden zinloos.
- Zet time-outs op uw eigen uitgaande aanroepen zodat een trage afhankelijkheid snel faalt met een duidelijke fout in plaats van een worker te verbruiken tot de proxy opgeeft.
Responstijd is de vroege waarschuwing
Een 504 is de eindtoestand van een vertraging die al een tijdje aan het opbouwen was. Responstijden drijven af van een halve seconde naar twee seconden naar tien, en niemand merkt het totdat verzoeken de limiet beginnen over te steken. Een geplande HTTP-check registreert de responstijd van elke check naast de statuscode, dus de trend is als grafiek zichtbaar lang voor de eerste time-out, en de waarschuwing komt bij de eerste echte mislukking in plaats van nadat de supportwachtrij vol raakt. Vanuit meerdere regio's controleren helpt ook, want een route die vanaf het ene continent snel is en vanaf het andere traag, wijst op het netwerkpad of de edge-configuratie in plaats van op uw database.