504 Gateway Timeout: Find the Cause and Fix Your Website

Wait briefly and refresh a normal read-only page once. Try another page on the website. If many websites fail only on your connection, compare another network or device. If this website keeps failing across networks, report the affected URL and time to its owner. Clearing a browser cannot repair an overloaded or unreachable upstream server.

For a checkout, booking, or form, resolve the original outcome before resubmitting. A timeout does not establish cancellation. The website’s operator can check its recorded state.

Example type: illustrative WordPress incident
Request: POST /wp-json/wp/v2/posts/42
Client status: 504
Gateway stage: waiting for upstream response headers
Operation state: check the stored draft before retrying
Application lead: outbound dependency in slowlog
Confirmation needed: matching request and dependency timing
Repair hypothesis: queue nonessential follow-up work
Verification: same authenticated update, full response,
stored draft, and background job result

Subject: Investigate a reproducible 504 Gateway Timeout

I have attached the incident record with the exact request,
timezone, received response, duration, scope, and operation state.

Please correlate it with the gateway and application records.
Which hop and stage timed out: connection, request sending,
response headers, response body, or another deadline?
Did the application start, finish, queue, or discard the work?
Is there a slow dependency, worker pressure, or a resource limit?

Please propose a scoped correction and verify the same action,
including its complete response and recorded application result.
Note the prior setting or rollback and remaining limits.

"""Owned local HTTP-gateway demonstration. Not Nginx, PHP, CDN, or a client site."""
import concurrent.futures, http.client, json, pathlib, socket, statistics, threading, time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

ROOT = pathlib.Path(__file__).resolve().parent
events=[]; lock=threading.Lock(); worker=threading.Semaphore(1); started=time.monotonic()
def log(kind,job,**details):
 with lock: events.append({'elapsed_s':round(time.monotonic()-started,4),'event':kind,'job':job,**details})
class Handler(BaseHTTPRequestHandler):
 def log_message(self,*args):pass
 def payload(self):return json.loads(self.rfile.read(int(self.headers.get('Content-Length','0'))))
 def reply(self,status,data):
  body=json.dumps(data).encode();self.send_response(status);self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(body)));self.end_headers()
  try:self.wfile.write(body)
  except (BrokenPipeError,ConnectionResetError):pass
class Origin(Handler):
 def do_POST(self):
  v=self.payload();job=v['job'];log('origin_received',job)
  if v.get('queued'):worker.acquire()
  try:
   log('origin_work_started',job);time.sleep(v['delay']);log('origin_work_completed',job)
   self.reply(200,{'job':job,'completed':True})
  finally:
   if v.get('queued'):worker.release()
class Gateway(Handler):
 def do_POST(self):
  v=self.payload();job=v['job'];log('gateway_received',job,budget_s=v['budget'])
  c=http.client.HTTPConnection('127.0.0.1',origin.server_port,timeout=v['budget'])
  try:
   c.request('POST','/work',body=json.dumps(v),headers={'Content-Type':'application/json'});r=c.getresponse();body=json.loads(r.read());log('gateway_response',job,status=r.status);self.reply(r.status,body)
  except (TimeoutError,socket.timeout):
   log('gateway_response',job,status=504);self.reply(504,{'job':job,'completed':'unknown at gateway','error':'upstream response timeout'})
  finally:c.close()

origin=ThreadingHTTPServer(('127.0.0.1',0),Origin);gateway=ThreadingHTTPServer(('127.0.0.1',0),Gateway)
for server in [origin,gateway]:threading.Thread(target=server.serve_forever,daemon=True).start()
def request(job,delay,budget,queued=False,client_timeout=2):
 v={'job':job,'delay':delay,'budget':budget,'queued':queued};c=http.client.HTTPConnection('127.0.0.1',gateway.server_port,timeout=client_timeout);t=time.monotonic()
 try:
  c.request('POST','/work',body=json.dumps(v),headers={'Content-Type':'application/json'});r=c.getresponse();body=json.loads(r.read());status=r.status
 except (TimeoutError,socket.timeout):status='client timeout, no HTTP status';body={}
 finally:c.close()
 return {'job':job,'origin_service_delay_s':delay,'gateway_read_budget_s':budget,'queued':queued,'client_timeout_s':client_timeout,'observed_status':status,'elapsed_s':round(time.monotonic()-t,4),'response':body}
results=[]
try:
 for repeat in range(1,4):
  for name,delay,budget in [('healthy',.04,.15),('slow',.4,.15),('longer_gateway_budget',.4,.65),('faster_origin',.03,.15)]:
   results.append(request(f'{name}-{repeat}',delay,budget));time.sleep(.45 if name=='slow' else .03)
  results.append(request(f'client_timeout-{repeat}',.25,.5,client_timeout=.06));time.sleep(.30)
 # Three requests share one application worker. Each service takes .12 s;
 # the third also waits behind the first two before its own work can start.
 for repeat in range(1,4):
  with concurrent.futures.ThreadPoolExecutor(max_workers=3) as pool:
   jobs=[pool.submit(request,f'queued-{repeat}-{n}',.12,.28,True) for n in range(1,4)]
   results.extend(j.result() for j in jobs)
  time.sleep(.45)
 time.sleep(.2)
 completed={e['job']:e['elapsed_s'] for e in events if e['event']=='origin_work_completed'}
 replies={e['job']:(e['elapsed_s'],e['status']) for e in events if e['event']=='gateway_response'}
 for r in results:
  r['origin_eventually_completed']=r['job'] in completed
  r['origin_completed_after_gateway_response']=r['job'] in replies and r['job'] in completed and completed[r['job']]>replies[r['job']][0]
 bycase={}
 for r in results:
  case=r['job'].split('-')[0];bycase.setdefault(case,[]).append(r)
 summaries=[{'case':case,'requests':len(rows),'statuses':[r['observed_status'] for r in rows],'median_elapsed_s':round(statistics.median(r['elapsed_s'] for r in rows),4),'all_origin_work_eventually_completed':all(r['origin_eventually_completed'] for r in rows)} for case,rows in bycase.items()]
 checks={
  'healthy_returns_200':all(r['observed_status']==200 for r in bycase['healthy']),
  'slow_returns_504':all(r['observed_status']==504 for r in bycase['slow']),
  'slow_work_completes_after_504':all(r['origin_completed_after_gateway_response'] for r in bycase['slow']),
  'longer_budget_waits_for_200':all(r['observed_status']==200 for r in bycase['longer_gateway_budget']),
  'faster_origin_restores_200':all(r['observed_status']==200 for r in bycase['faster_origin']),
  'client_timeout_has_no_http_status':all(r['observed_status']=='client timeout, no HTTP status' for r in bycase['client_timeout']),
  'every_queue_round_has_two_successes_one_timeout':all(sorted(r['observed_status'] for r in bycase['queued'] if r['job'].startswith('queued-'+str(n)+'-'))==[200,200,504] for n in range(1,4)),
  'all_queued_work_eventually_completes':all(r['origin_eventually_completed'] for r in bycase['queued'])
 }
 payload={'scope':'Python standard-library origin and gateway on localhost; synthetic delays; no WordPress/Nginx/Cloudflare production testing','repetitions_per_case':3,'summaries':summaries,'checks':checks,'results':results,'events':events}
 (ROOT/'timeout-lab-results.json').write_text(json.dumps(payload,indent=2));print(json.dumps({'scope':payload['scope'],'summaries':summaries,'checks':checks},indent=2))
 if not all(checks.values()):raise SystemExit('A lab expectation failed; inspect results before using')
finally:
 gateway.shutdown();origin.shutdown();gateway.server_close();origin.server_close()

"""Local queue-policy contrast: discard expired work before it starts. Not WP Engine."""
import concurrent.futures, http.client, json, pathlib, socket, statistics, threading, time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

ROOT = pathlib.Path(__file__).resolve().parent
events=[]; lock=threading.Lock(); worker=threading.Semaphore(1); started=time.monotonic()
def log(kind,job,**details):
 with lock: events.append({'elapsed_s':round(time.monotonic()-started,4),'event':kind,'job':job,**details})
class Handler(BaseHTTPRequestHandler):
 def log_message(self,*args):pass
 def payload(self):return json.loads(self.rfile.read(int(self.headers.get('Content-Length','0'))))
 def reply(self,status,data):
  body=json.dumps(data).encode();self.send_response(status);self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(body)));self.end_headers()
  try:self.wfile.write(body)
  except (BrokenPipeError,ConnectionResetError):pass
class Origin(Handler):
 def do_POST(self):
  v=self.payload();job=v['job'];log('origin_received',job)
  if v.get('queued'):worker.acquire()
  try:
   if time.monotonic()-v['sent_at'] >= v['budget']:
    log('origin_work_discarded_before_start',job);self.reply(504,{'job':job,'completed':False,'discarded':True});return
   log('origin_work_started',job);time.sleep(v['delay']);log('origin_work_completed',job)
   self.reply(200,{'job':job,'completed':True})
  finally:
   if v.get('queued'):worker.release()
class Gateway(Handler):
 def do_POST(self):
  v=self.payload();job=v['job'];log('gateway_received',job,budget_s=v['budget'])
  c=http.client.HTTPConnection('127.0.0.1',origin.server_port,timeout=v['budget'])
  try:
   c.request('POST','/work',body=json.dumps(v),headers={'Content-Type':'application/json'});r=c.getresponse();body=json.loads(r.read());log('gateway_response',job,status=r.status);self.reply(r.status,body)
  except (TimeoutError,socket.timeout):
   log('gateway_response',job,status=504);self.reply(504,{'job':job,'completed':'unknown at gateway','error':'upstream response timeout'})
  finally:c.close()

origin=ThreadingHTTPServer(('127.0.0.1',0),Origin);gateway=ThreadingHTTPServer(('127.0.0.1',0),Gateway)
for server in [origin,gateway]:threading.Thread(target=server.serve_forever,daemon=True).start()
def request(job,delay,budget,queued=False,client_timeout=2):
 v={'job':job,'delay':delay,'budget':budget,'queued':queued,'sent_at':time.monotonic()};c=http.client.HTTPConnection('127.0.0.1',gateway.server_port,timeout=client_timeout);t=time.monotonic()
 try:
  c.request('POST','/work',body=json.dumps(v),headers={'Content-Type':'application/json'});r=c.getresponse();body=json.loads(r.read());status=r.status
 except (TimeoutError,socket.timeout):status='client timeout, no HTTP status';body={}
 finally:c.close()
 return {'job':job,'origin_service_delay_s':delay,'gateway_read_budget_s':budget,'queued':queued,'client_timeout_s':client_timeout,'observed_status':status,'elapsed_s':round(time.monotonic()-t,4),'response':body}
results=[]
try:
 for repeat in range(1,4):
  with concurrent.futures.ThreadPoolExecutor(max_workers=3) as pool:
   jobs=[pool.submit(request,f'policy-{repeat}-{n}',.12,.18,True) for n in range(1,4)]
   results.extend(j.result() for j in jobs)
  time.sleep(.4)
 time.sleep(.2)
 completed={e['job']:e['elapsed_s'] for e in events if e['event']=='origin_work_completed'}
 replies={e['job']:(e['elapsed_s'],e['status']) for e in events if e['event']=='gateway_response'}
 for r in results:
  r['origin_eventually_completed']=r['job'] in completed
  r['origin_completed_after_gateway_response']=r['job'] in replies and r['job'] in completed and completed[r['job']]>replies[r['job']][0]
 bycase={}
 for r in results:
  case=r['job'].split('-')[0];bycase.setdefault(case,[]).append(r)
 summaries=[{'case':case,'requests':len(rows),'statuses':[r['observed_status'] for r in rows],'median_elapsed_s':round(statistics.median(r['elapsed_s'] for r in rows),4),'all_origin_work_eventually_completed':all(r['origin_eventually_completed'] for r in rows)} for case,rows in bycase.items()]
 discarded={e['job'] for e in events if e['event']=='origin_work_discarded_before_start'}
 begun={e['job'] for e in events if e['event']=='origin_work_started'}
 checks={
  'each_round_one_200_two_504':all(sorted(r['observed_status'] for r in results if r['job'].startswith('policy-'+str(n)+'-'))==[200,504,504] for n in range(1,4)),
  'each_round_has_both_timeout_outcomes':all(sorted(r['origin_eventually_completed'] for r in results if r['observed_status']==504 and r['job'].startswith('policy-'+str(n)+'-'))==[False,True] for n in range(1,4)),
  'three_expired_jobs_discarded':len(discarded)==3,
  'discarded_jobs_never_started':not (discarded & begun)
 }

 payload={'scope':'Owned Python gateway and single-worker synthetic origin; expired queued work discarded before start; not WP Engine or a production test','repetitions_per_case':3,'summaries':summaries,'checks':checks,'results':results,'events':events}
 (ROOT/'queue-policy-lab-results.json').write_text(json.dumps(payload,indent=2));print(json.dumps({'scope':payload['scope'],'summaries':summaries,'checks':checks},indent=2))
 if not all(checks.values()):raise SystemExit('A lab expectation failed; inspect results before using')
finally:
 gateway.shutdown();origin.shutdown();gateway.server_close();origin.server_close()

"""Synthetic HTTP/1.1 model: deadline before headers vs stall after forwarding 200.

Python standard library only. This is not Nginx, PHP, WordPress, or production.
Reruns replace the adjacent JSON file. Original measured output is packaged.
"""
import http.client
import json
import pathlib
import socket
import statistics
import threading
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import parse_qs, urlsplit

ROOT = pathlib.Path(__file__).resolve().parent
events = []
event_lock = threading.Lock()
started = time.monotonic()
PAYLOAD = b'ready-DONE'
PREFIX = b'ready-'
READ_GAP = 0.08

def record(event, job, **fields):
    with event_lock:
        events.append({'elapsed_s': round(time.monotonic()-started, 6), 'event': event, 'job': job, **fields})

class Base(BaseHTTPRequestHandler):
    protocol_version = 'HTTP/1.1'
    def log_message(self, *args): pass
    def send_body(self, status, body):
        self.send_response(status)
        self.send_header('Content-Type', 'text/plain')
        self.send_header('Content-Length', str(len(body)))
        self.send_header('Connection', 'close')
        self.end_headers()
        try:
            self.wfile.write(body);self.wfile.flush()
        except (BrokenPipeError, ConnectionResetError): pass
        self.close_connection = True

class Origin(Base):
    def do_GET(self):
        q = parse_qs(urlsplit(self.path).query)
        case = q['case'][0];job = q['job'][0]
        record('origin_received', job)
        if case == 'before_headers': time.sleep(0.20)
        self.send_response(200)
        self.send_header('Content-Type', 'text/plain')
        self.send_header('Content-Length', str(len(PAYLOAD)))
        self.send_header('Connection', 'close')
        self.end_headers();record('origin_headers_sent', job, status=200)
        try:
            self.wfile.write(PREFIX);self.wfile.flush()
            record('origin_prefix_sent', job, bytes=len(PREFIX))
            if case == 'after_headers': time.sleep(0.20)
            else: time.sleep(0.01)
            self.wfile.write(PAYLOAD[len(PREFIX):]);self.wfile.flush()
            record('origin_body_sent', job, bytes=len(PAYLOAD))
        except (BrokenPipeError, ConnectionResetError): record('origin_client_connection_closed', job)
        self.close_connection = True

class Gateway(Base):
    def do_GET(self):
        q = parse_qs(urlsplit(self.path).query);job = q['job'][0]
        record('gateway_received', job, read_gap_s=READ_GAP)
        conn = http.client.HTTPConnection('127.0.0.1', origin.server_port, timeout=READ_GAP)
        sent_headers = False
        try:
            conn.request('GET', self.path)
            upstream = conn.getresponse()
            self.send_response(upstream.status)
            self.send_header('Content-Type', 'text/plain')
            self.send_header('Content-Length', upstream.getheader('Content-Length'))
            self.send_header('Connection', 'close')
            self.end_headers();sent_headers = True
            record('gateway_headers_forwarded', job, status=upstream.status)
            sent = 0
            while True:
                chunk = upstream.read(1)
                if not chunk: break
                self.wfile.write(chunk);self.wfile.flush();sent += len(chunk)
                record('gateway_body_byte_forwarded', job, bytes=sent)
            record('gateway_body_complete', job, bytes=sent)
        except (socket.timeout, TimeoutError):
            if not sent_headers:
                record('gateway_timeout_before_headers', job)
                self.send_body(504, b'gateway deadline before response headers')
                record('gateway_headers_forwarded', job, status=504)
            else:
                record('gateway_timeout_after_headers', job, sent_status=200)
                # The existing 200 headers cannot be replaced. Close the body.
        except (BrokenPipeError, ConnectionResetError): record('gateway_client_connection_closed', job)
        finally:
            conn.close();self.close_connection = True

origin = ThreadingHTTPServer(('127.0.0.1', 0), Origin)
gateway = ThreadingHTTPServer(('127.0.0.1', 0), Gateway)
for server in (origin, gateway):
    threading.Thread(target=server.serve_forever, daemon=True).start()

results = []
try:
    for repetition in range(1, 4):
        for case in ('healthy', 'before_headers', 'after_headers'):
            job = f'{case}-{repetition}'
            conn = http.client.HTTPConnection('127.0.0.1', gateway.server_port, timeout=2)
            tick = time.monotonic();status = None;body = b'';error = None
            try:
                conn.request('GET', f'/work?case={case}&job={job}')
                response = conn.getresponse();status = response.status
                try: body = response.read()
                except http.client.IncompleteRead as e:
                    body = e.partial;error = 'IncompleteRead'
            finally: conn.close()
            results.append({'job':job,'case':case,'observed_status':status,'client_body':body.decode(),'received_body_bytes':len(body),'expected_origin_body_bytes':len(PAYLOAD),'expected_origin_payload_received':case != 'before_headers' and body == PAYLOAD,'http_response_framing_complete':error is None,'client_error':error,'elapsed_s':round(time.monotonic()-tick,6)})
    # Join outstanding synthetic origin delays before retaining the event record.
    time.sleep(0.25)
finally:
    for server in (gateway, origin):server.shutdown();server.server_close()

by_case = {case:[r for r in results if r['case']==case] for case in ('healthy','before_headers','after_headers')}
checks = {
    'healthy_returns_200_in_all_three':all(r['observed_status']==200 for r in by_case['healthy']),
    'healthy_full_body_in_all_three':all(r['expected_origin_payload_received'] for r in by_case['healthy']),
    'before_headers_returns_504_in_all_three':all(r['observed_status']==504 for r in by_case['before_headers']),
    'after_headers_preserves_200_in_all_three':all(r['observed_status']==200 for r in by_case['after_headers']),
    'after_headers_body_is_incomplete_in_all_three':all(r['client_error']=='IncompleteRead' and r['received_body_bytes']==len(PREFIX) for r in by_case['after_headers']),
    'each_body_timeout_follows_forwarded_200':all(next(e['elapsed_s'] for e in events if e['job']==r['job'] and e['event']=='gateway_headers_forwarded') < next(e['elapsed_s'] for e in events if e['job']==r['job'] and e['event']=='gateway_timeout_after_headers') for r in by_case['after_headers'])
}
summary = [{'case':case,'requests':len(rows),'statuses':[r['observed_status'] for r in rows],'median_elapsed_ms':round(statistics.median(r['elapsed_s'] for r in rows)*1000,1),'complete_origin_payload_count':sum(r['expected_origin_payload_received'] for r in rows),'client_errors':[r['client_error'] for r in rows]} for case,rows in by_case.items()]
output = {'scope':'Owned Python HTTP/1.1 origin/gateway on localhost with an 80ms read gap; synthetic timing only, not Nginx/PHP/WordPress/Cloudflare or production.','repetitions_per_case':3,'summary':summary,'checks':checks,'results':results,'events':events}
(ROOT/'header-body-timeout-results.json').write_text(json.dumps(output,indent=2))
print(json.dumps({'summary':summary,'checks':checks},indent=2))
if not all(checks.values()):raise SystemExit('A defined experiment check failed; inspect retained data.')

{
  "scope": "Owned synthetic localhost models; individual request records, not production tests.",
  "selected_continuation_request": {
    "job": "slow-1",
    "origin_service_delay_s": 0.4,
    "gateway_read_budget_s": 0.15,
    "queued": false,
    "client_timeout_s": 2,
    "observed_status": 504,
    "elapsed_s": 0.1529,
    "response": {
      "job": "slow-1",
      "completed": "unknown at gateway",
      "error": "upstream response timeout"
    },
    "origin_eventually_completed": true,
    "origin_completed_after_gateway_response": true
  },
  "plot_values": [
    {
      "job": "slow-1",
      "label": "Work continued; 150 ms gateway budget",
      "gateway_budget_ms": 150.0,
      "origin_received_ms": 1.3,
      "work_started_ms": 1.3,
      "work_completed_ms": 401.5,
      "work_discarded_ms": null,
      "gateway_response_ms": 150.7,
      "observed_status": 504,
      "source_file": "timeout-lab-results.json"
    },
    {
      "job": "policy-1-2",
      "label": "Queued work continued; 180 ms gateway budget",
      "gateway_budget_ms": 180.0,
      "origin_received_ms": 1.1,
      "work_started_ms": 121.0,
      "work_completed_ms": 241.1,
      "work_discarded_ms": null,
      "gateway_response_ms": 181.4,
      "observed_status": 504,
      "source_file": "queue-policy-lab-results.json"
    },
    {
      "job": "policy-1-3",
      "label": "Expired queued work discarded; 180 ms gateway budget",
      "gateway_budget_ms": 180.0,
      "origin_received_ms": 0.5,
      "work_started_ms": null,
      "work_completed_ms": null,
      "work_discarded_ms": 240.4,
      "gateway_response_ms": 180.7,
      "observed_status": 504,
      "source_file": "queue-policy-lab-results.json"
    }
  ],
  "header_body_summary": [
    {
      "case": "healthy",
      "requests": 3,
      "statuses": [
        200,
        200,
        200
      ],
      "median_elapsed_ms": 13.3,
      "client_errors": [
        null,
        null,
        null
      ],
      "complete_origin_payload_count": 3
    },
    {
      "case": "before_headers",
      "requests": 3,
      "statuses": [
        504,
        504,
        504
      ],
      "median_elapsed_ms": 81.5,
      "client_errors": [
        null,
        null,
        null
      ],
      "complete_origin_payload_count": 0
    },
    {
      "case": "after_headers",
      "requests": 3,
      "statuses": [
        200,
        200,
        200
      ],
      "median_elapsed_ms": 82.5,
      "client_errors": [
        "IncompleteRead",
        "IncompleteRead",
        "IncompleteRead"
      ],
      "complete_origin_payload_count": 0
    }
  ],
  "header_body_checks": {
    "healthy_returns_200_in_all_three": true,
    "healthy_full_body_in_all_three": true,
    "before_headers_returns_504_in_all_three": true,
    "after_headers_preserves_200_in_all_three": true,
    "after_headers_body_is_incomplete_in_all_three": true,
    "each_body_timeout_follows_forwarded_200": true
  }
}