Error guide

5xx server errors

The class meaning the server failed to fulfil a request that was, as far as it could tell, valid.

A 5xx status means the server failed to fulfil a request that appeared valid. Responsibility sits with the server side — the application, its dependencies, or the infrastructure in front of it. Unlike a 4xx, no change the client could make would have avoided it.

This is the class monitoring exists for, and every code in it should fail a check by default. It is also the class most visible to customers, because a 5xx usually means a request that should have worked did not.

The specific code narrows down which layer failed, which is most of the initial triage: 500 is the application throwing; 502 and 504 are a proxy reporting that something behind it failed or was too slow; 503 is a deliberate refusal because of capacity or maintenance; 501 is a method the server does not implement. Getting to the right layer quickly is worth more than any amount of guessing at causes.

Common causes

  • An unhandled exception in application code.
  • A dependency — database, cache, queue, third-party API — failing or timing out.
  • Resource exhaustion: memory, file descriptors, connection pools, disk.
  • A deploy that shipped a bug, or a configuration change that broke a connection.
  • An upstream service that is down, unreachable or answering too slowly.

How to diagnose it

  1. Read the exact code first: it identifies the layer, and the layer determines where to look.
  2. Check whether the error is in your application log or only in the proxy's — that alone splits the search in half.
  3. Establish whether it affects all requests or a subset, which distinguishes a total failure from a partial one.
  4. Correlate the start time against deploys, configuration changes and dependency incidents.
  5. Check the health of every dependency before debugging your own code; most 5xx incidents are somebody else's outage arriving.

Whose fault is it? The server's side

By definition the server side, though a 5xx is frequently caused by a dependency rather than by the application itself — which is still your incident even when it is not your bug.

What monitoring sees

Uptimely's default criteria fail a check on a 5xx and record the exact code. A monitor declares an incident once the failure threshold is met — two consecutive failed checks by default — so a single blip is recorded as downtime without paging anyone, while a sustained 5xx opens an incident and runs the on-call policy.

Related error guides

Terms used on this page

Questions

Should every 5xx trigger an alert?

Every 5xx should fail the check. Whether it alerts depends on the threshold: waiting for two consecutive failures removes single blips while still recording them as downtime, which is almost always the right default.

Which 5xx codes point at a proxy rather than my app?

502 and 504 are generated by something in front of your application — a reverse proxy or CDN reporting that the upstream failed or was too slow. A 500 comes from the application itself.

One of the Uptimely HTTP and network error guides, written for the person who operates the server rather than the one refreshing the page. Something here read wrong to you? Email support@getuptimely.com.