[{"data":1,"prerenderedAt":642},["ShallowReactive",2],{"content-query-2K8W6ND1Ib":3},{"_path":4,"_dir":5,"_draft":6,"_partial":6,"_locale":7,"title":8,"description":9,"layout":10,"crumb":11,"summary":12,"group":13,"order":14,"code":14,"updated":15,"cta":16,"related":24,"faq":43,"body":59,"_type":635,"_id":636,"_source":637,"_file":638,"_stem":639,"_extension":640,"sitemap":641},"/http-errors/503-service-unavailable","http-errors",false,"","503 Service Unavailable: what it means and how to fix it","503 Service Unavailable means the server is overloaded or down for maintenance. Causes, Retry-After, and fixes for nginx, Kubernetes and AWS ALB.","reference","503 Service Unavailable","The server is temporarily overloaded or in maintenance. Retry later.","5xx server errors",503,"2026-10-28",{"eyebrow":17,"title":18,"text":19,"to":20,"label":21,"secondaryTo":22,"secondaryLabel":23},"Webhook Relay Durable Retries","Deploy without dropping webhooks","During a deploy or outage your endpoint answers 503 and providers start their short retry clocks. Webhook Relay stores each webhook and retries with exponential backoff for up to 30 days, so events wait until your endpoint is back.","/features/durable-retries/","See durable retries","/docs/webhooks/durable-webhooks/","Durable webhooks docs",[25,28,31,34,37,40],{"title":26,"to":27},"429 Too Many Requests","/http-errors/429-too-many-requests/",{"title":29,"to":30},"502 Bad Gateway","/http-errors/502-bad-gateway/",{"title":32,"to":33},"504 Gateway Timeout","/http-errors/504-gateway-timeout/",{"title":35,"to":36},"Exponential backoff","/glossary/exponential-backoff/",{"title":38,"to":39},"Dead letter queue","/glossary/dead-letter-queue/",{"title":41,"to":42},"Webhook throttling","/features/throttling/",[44,47,50,53,56],{"q":45,"a":46},"What does 503 Service Unavailable mean?","HTTP 503 means the server can't handle the request right now because it is overloaded, down for maintenance, or has no healthy backend to send it to. The condition is meant to be temporary. The server may include a Retry-After header saying when to try again.",{"q":48,"a":49},"How long does a 503 error last?","It depends on the cause. A deploy or restart usually clears in seconds to minutes, an overload clears when traffic drops or capacity is added, and planned maintenance lasts as long as the window. If the response has a Retry-After header, that's the server's own estimate.",{"q":51,"a":52},"What is the difference between 503 and 429?","429 Too Many Requests means you, a specific client, are over your rate limit while the service works fine for others. 503 Service Unavailable means the service as a whole can't take requests right now, for everyone.",{"q":54,"a":55},"Why does nginx return 503?","Two common reasons. First, the limit_req or limit_conn modules reject excess requests with 503 by default, unless you set limit_req_status to 429. Second, the configuration returns 503 on purpose, typically a maintenance page set up with return 503 or an error_page rule. Check the error log for limiting requests, and grep the config for 503.",{"q":57,"a":58},"Do webhook providers retry a 503?","Most providers retry 5xx responses, and some honour the Retry-After header on a 503. But each provider has its own retry window, often hours or a few days, sometimes minutes. A long outage can outlast it.",{"type":60,"children":61,"toc":627},"root",[62,90,148,155,234,240,245,251,409,428,434,531,537,542,575,581,621],{"type":63,"tag":64,"props":65,"children":66},"element","p",{},[67,80,82,88],{"type":63,"tag":68,"props":69,"children":70},"strong",{},[71,78],{"type":63,"tag":72,"props":73,"children":75},"code",{"className":74},[],[76],{"type":77,"value":11},"text",{"type":77,"value":79}," means the server can't handle the request right now because it's overloaded, down for maintenance, or has no healthy backend to route to.",{"type":77,"value":81}," Unlike a 500, it signals a temporary condition. The server may include a ",{"type":63,"tag":72,"props":83,"children":85},{"className":84},[],[86],{"type":77,"value":87},"Retry-After",{"type":77,"value":89}," header with its estimate of when to try again.",{"type":63,"tag":91,"props":92,"children":96},"pre",{"className":93,"code":94,"language":95,"meta":7,"style":7},"language-http shiki shiki-themes github-dark","HTTP/1.1 503 Service Unavailable\nRetry-After: 120\nContent-Type: application/json\n\n{\"error\": \"maintenance\", \"message\": \"Scheduled maintenance, back in about 2 minutes\"}\n","http",[97],{"type":63,"tag":72,"props":98,"children":99},{"__ignoreMap":7},[100,111,120,129,139],{"type":63,"tag":101,"props":102,"children":105},"span",{"class":103,"line":104},"line",1,[106],{"type":63,"tag":101,"props":107,"children":108},{},[109],{"type":77,"value":110},"HTTP/1.1 503 Service Unavailable\n",{"type":63,"tag":101,"props":112,"children":114},{"class":103,"line":113},2,[115],{"type":63,"tag":101,"props":116,"children":117},{},[118],{"type":77,"value":119},"Retry-After: 120\n",{"type":63,"tag":101,"props":121,"children":123},{"class":103,"line":122},3,[124],{"type":63,"tag":101,"props":125,"children":126},{},[127],{"type":77,"value":128},"Content-Type: application/json\n",{"type":63,"tag":101,"props":130,"children":132},{"class":103,"line":131},4,[133],{"type":63,"tag":101,"props":134,"children":136},{"emptyLinePlaceholder":135},true,[137],{"type":77,"value":138},"\n",{"type":63,"tag":101,"props":140,"children":142},{"class":103,"line":141},5,[143],{"type":63,"tag":101,"props":144,"children":145},{},[146],{"type":77,"value":147},"{\"error\": \"maintenance\", \"message\": \"Scheduled maintenance, back in about 2 minutes\"}\n",{"type":63,"tag":149,"props":150,"children":152},"h2",{"id":151},"common-causes",[153],{"type":77,"value":154},"Common causes",{"type":63,"tag":156,"props":157,"children":158},"ul",{},[159,170,180,190,224],{"type":63,"tag":160,"props":161,"children":162},"li",{},[163,168],{"type":63,"tag":68,"props":164,"children":165},{},[166],{"type":77,"value":167},"Planned maintenance.",{"type":77,"value":169}," The app or a load balancer returns a maintenance page with 503.",{"type":63,"tag":160,"props":171,"children":172},{},[173,178],{"type":63,"tag":68,"props":174,"children":175},{},[176],{"type":77,"value":177},"Overload.",{"type":77,"value":179}," Every worker or thread is busy, connection pools are exhausted, or an autoscaler hasn't caught up yet.",{"type":63,"tag":160,"props":181,"children":182},{},[183,188],{"type":63,"tag":68,"props":184,"children":185},{},[186],{"type":77,"value":187},"No healthy backends.",{"type":77,"value":189}," An AWS ALB target group with no healthy targets, a Kubernetes Service with no ready pods, or a deploy that took every instance down at once.",{"type":63,"tag":160,"props":191,"children":192},{},[193,198,200,206,208,214,216,222],{"type":63,"tag":68,"props":194,"children":195},{},[196],{"type":77,"value":197},"Rate or connection limits.",{"type":77,"value":199}," nginx ",{"type":63,"tag":72,"props":201,"children":203},{"className":202},[],[204],{"type":77,"value":205},"limit_req",{"type":77,"value":207}," and ",{"type":63,"tag":72,"props":209,"children":211},{"className":210},[],[212],{"type":77,"value":213},"limit_conn",{"type":77,"value":215}," reject excess requests with ",{"type":63,"tag":72,"props":217,"children":219},{"className":218},[],[220],{"type":77,"value":221},"503",{"type":77,"value":223}," by default.",{"type":63,"tag":160,"props":225,"children":226},{},[227,232],{"type":63,"tag":68,"props":228,"children":229},{},[230],{"type":77,"value":231},"A dependency outage.",{"type":77,"value":233}," The app deliberately answers 503 when its database or a required service is down.",{"type":63,"tag":149,"props":235,"children":237},{"id":236},"how-to-fix-it-as-a-visitor",[238],{"type":77,"value":239},"How to fix it as a visitor",{"type":63,"tag":64,"props":241,"children":242},{},[243],{"type":77,"value":244},"Wait and retry. Most 503s clear within minutes. Check the service's status page or social accounts for maintenance notices. Repeated refreshing during an overload makes it worse for everyone.",{"type":63,"tag":149,"props":246,"children":248},{"id":247},"how-to-fix-it-as-a-developer-or-ops",[249],{"type":77,"value":250},"How to fix it as a developer or ops",{"type":63,"tag":252,"props":253,"children":254},"table",{},[255,279],{"type":63,"tag":256,"props":257,"children":258},"thead",{},[259],{"type":63,"tag":260,"props":261,"children":262},"tr",{},[263,269,274],{"type":63,"tag":264,"props":265,"children":266},"th",{},[267],{"type":77,"value":268},"Where",{"type":63,"tag":264,"props":270,"children":271},{},[272],{"type":77,"value":273},"Likely cause",{"type":63,"tag":264,"props":275,"children":276},{},[277],{"type":77,"value":278},"Fix",{"type":63,"tag":280,"props":281,"children":282},"tbody",{},[283,331,355,373,391],{"type":63,"tag":260,"props":284,"children":285},{},[286,292,303],{"type":63,"tag":287,"props":288,"children":289},"td",{},[290],{"type":77,"value":291},"nginx",{"type":63,"tag":287,"props":293,"children":294},{},[295,301],{"type":63,"tag":72,"props":296,"children":298},{"className":297},[],[299],{"type":77,"value":300},"limiting requests",{"type":77,"value":302}," in the error log",{"type":63,"tag":287,"props":304,"children":305},{},[306,308,313,315,321,323,329],{"type":77,"value":307},"Raise the ",{"type":63,"tag":72,"props":309,"children":311},{"className":310},[],[312],{"type":77,"value":205},{"type":77,"value":314}," rate or ",{"type":63,"tag":72,"props":316,"children":318},{"className":317},[],[319],{"type":77,"value":320},"burst",{"type":77,"value":322},", or set ",{"type":63,"tag":72,"props":324,"children":326},{"className":325},[],[327],{"type":77,"value":328},"limit_req_status 429;",{"type":77,"value":330}," so clients see the correct code.",{"type":63,"tag":260,"props":332,"children":333},{},[334,339,344],{"type":63,"tag":287,"props":335,"children":336},{},[337],{"type":77,"value":338},"ingress-nginx / Kubernetes",{"type":63,"tag":287,"props":340,"children":341},{},[342],{"type":77,"value":343},"Service has no ready endpoints",{"type":63,"tag":287,"props":345,"children":346},{},[347,353],{"type":63,"tag":72,"props":348,"children":350},{"className":349},[],[351],{"type":77,"value":352},"kubectl get endpoints \u003Csvc>",{"type":77,"value":354},"; fix failing readiness probes or the selector.",{"type":63,"tag":260,"props":356,"children":357},{},[358,363,368],{"type":63,"tag":287,"props":359,"children":360},{},[361],{"type":77,"value":362},"AWS ALB",{"type":63,"tag":287,"props":364,"children":365},{},[366],{"type":77,"value":367},"No registered or healthy targets",{"type":63,"tag":287,"props":369,"children":370},{},[371],{"type":77,"value":372},"Check target health and the health-check path; make sure deploys keep some targets in service.",{"type":63,"tag":260,"props":374,"children":375},{},[376,381,386],{"type":63,"tag":287,"props":377,"children":378},{},[379],{"type":77,"value":380},"Cloudflare",{"type":63,"tag":287,"props":382,"children":383},{},[384],{"type":77,"value":385},"Origin or Worker overloaded",{"type":63,"tag":287,"props":387,"children":388},{},[389],{"type":77,"value":390},"Check origin capacity; a 503 from Cloudflare itself can also mean a Worker exceeded its limits.",{"type":63,"tag":260,"props":392,"children":393},{},[394,399,404],{"type":63,"tag":287,"props":395,"children":396},{},[397],{"type":77,"value":398},"App servers",{"type":63,"tag":287,"props":400,"children":401},{},[402],{"type":77,"value":403},"Workers saturated",{"type":63,"tag":287,"props":405,"children":406},{},[407],{"type":77,"value":408},"Add workers or instances, fix slow queries, add caching.",{"type":63,"tag":64,"props":410,"children":411},{},[412,414,419,421,426],{"type":77,"value":413},"Two general practices prevent most 503s during deploys: ",{"type":63,"tag":68,"props":415,"children":416},{},[417],{"type":77,"value":418},"rolling deploys",{"type":77,"value":420}," that keep some instances serving, and ",{"type":63,"tag":68,"props":422,"children":423},{},[424],{"type":77,"value":425},"readiness checks",{"type":77,"value":427}," that only route traffic to instances that have finished starting.",{"type":63,"tag":149,"props":429,"children":431},{"id":430},"handling-a-503-as-an-api-client",[432],{"type":77,"value":433},"Handling a 503 as an API client",{"type":63,"tag":435,"props":436,"children":437},"ol",{},[438,463,480,521],{"type":63,"tag":160,"props":439,"children":440},{},[441,453,455,461],{"type":63,"tag":68,"props":442,"children":443},{},[444,446,451],{"type":77,"value":445},"Honour ",{"type":63,"tag":72,"props":447,"children":449},{"className":448},[],[450],{"type":77,"value":87},{"type":77,"value":452},".",{"type":77,"value":454}," It's either a number of seconds (",{"type":63,"tag":72,"props":456,"children":458},{"className":457},[],[459],{"type":77,"value":460},"Retry-After: 120",{"type":77,"value":462},") or an HTTP date. Don't retry before then.",{"type":63,"tag":160,"props":464,"children":465},{},[466,471,473,479],{"type":63,"tag":68,"props":467,"children":468},{},[469],{"type":77,"value":470},"Otherwise back off exponentially with jitter",{"type":77,"value":472},": 1s, 2s, 4s, 8s plus a random offset, with a cap on attempts. See ",{"type":63,"tag":474,"props":475,"children":476},"a",{"href":36},[477],{"type":77,"value":478},"exponential backoff",{"type":77,"value":452},{"type":63,"tag":160,"props":481,"children":482},{},[483,488,490,496,498,504,505,511,513,519],{"type":63,"tag":68,"props":484,"children":485},{},[486],{"type":77,"value":487},"Only retry safe requests automatically.",{"type":77,"value":489}," ",{"type":63,"tag":72,"props":491,"children":493},{"className":492},[],[494],{"type":77,"value":495},"GET",{"type":77,"value":497},", ",{"type":63,"tag":72,"props":499,"children":501},{"className":500},[],[502],{"type":77,"value":503},"PUT",{"type":77,"value":207},{"type":63,"tag":72,"props":506,"children":508},{"className":507},[],[509],{"type":77,"value":510},"DELETE",{"type":77,"value":512}," are idempotent. Retry a ",{"type":63,"tag":72,"props":514,"children":516},{"className":515},[],[517],{"type":77,"value":518},"POST",{"type":77,"value":520}," only if the API supports idempotency keys, or you may create the same thing twice.",{"type":63,"tag":160,"props":522,"children":523},{},[524,529],{"type":63,"tag":68,"props":525,"children":526},{},[527],{"type":77,"value":528},"Use a circuit breaker",{"type":77,"value":530}," for dependencies that return 503 repeatedly, so your own service fails fast instead of piling up waiting requests.",{"type":63,"tag":149,"props":532,"children":534},{"id":533},"_503s-on-a-webhook-endpoint",[535],{"type":77,"value":536},"503s on a webhook endpoint",{"type":63,"tag":64,"props":538,"children":539},{},[540],{"type":77,"value":541},"Deploys are the most common source of webhook 503s. For a minute or two, every delivery fails. Providers retry, but their retry windows are short and each one is different, and a longer outage can run past the window entirely.",{"type":63,"tag":64,"props":543,"children":544},{},[545,547,552,554,558,560,566,568,573],{"type":77,"value":546},"Webhook Relay ",{"type":63,"tag":474,"props":548,"children":549},{"href":20},[550],{"type":77,"value":551},"durable retries",{"type":77,"value":553}," take that timing out of the provider's hands. Every event is stored before delivery and retried with ",{"type":63,"tag":474,"props":555,"children":556},{"href":36},[557],{"type":77,"value":478},{"type":77,"value":559}," for up to 30 days, so webhooks sent during a deploy or outage wait until your endpoint returns ",{"type":63,"tag":72,"props":561,"children":563},{"className":562},[],[564],{"type":77,"value":565},"2xx",{"type":77,"value":567},". If the 503s come from overload rather than downtime, ",{"type":63,"tag":474,"props":569,"children":570},{"href":42},[571],{"type":77,"value":572},"outbound throttling",{"type":77,"value":574}," releases events at a fixed rate or concurrency so a burst never saturates your workers in the first place.",{"type":63,"tag":149,"props":576,"children":578},{"id":577},"when-to-return-503-from-your-own-api",[579],{"type":77,"value":580},"When to return 503 from your own API",{"type":63,"tag":64,"props":582,"children":583},{},[584,586,591,593,598,600,608,610,620],{"type":77,"value":585},"Return ",{"type":63,"tag":72,"props":587,"children":589},{"className":588},[],[590],{"type":77,"value":221},{"type":77,"value":592}," when the whole service, or a whole endpoint, is temporarily unable to serve anyone: maintenance, overload, a required dependency down. Include ",{"type":63,"tag":72,"props":594,"children":596},{"className":595},[],[597],{"type":77,"value":87},{"type":77,"value":599}," (seconds or an HTTP date) so well-behaved clients wait instead of hammering you. If only one client is over its quota, use ",{"type":63,"tag":474,"props":601,"children":602},{"href":27},[603],{"type":63,"tag":72,"props":604,"children":606},{"className":605},[],[607],{"type":77,"value":26},{"type":77,"value":609},". If your code simply crashed, that's a ",{"type":63,"tag":474,"props":611,"children":613},{"href":612},"/http-errors/500-internal-server-error/",[614],{"type":63,"tag":72,"props":615,"children":617},{"className":616},[],[618],{"type":77,"value":619},"500",{"type":77,"value":452},{"type":63,"tag":622,"props":623,"children":624},"style",{},[625],{"type":77,"value":626},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":7,"searchDepth":122,"depth":122,"links":628},[629,630,631,632,633,634],{"id":151,"depth":113,"text":154},{"id":236,"depth":113,"text":239},{"id":247,"depth":113,"text":250},{"id":430,"depth":113,"text":433},{"id":533,"depth":113,"text":536},{"id":577,"depth":113,"text":580},"markdown","content:http-errors:503-service-unavailable.md","content","http-errors/503-service-unavailable.md","http-errors/503-service-unavailable","md",{"loc":4},1793199803071]