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.
| Code | Name | Defined in |
|---|---|---|
| 500 | Internal Server Error | RFC 9110 |
| 501 | Not Implemented | RFC 9110 |
| 502 | Bad Gateway | RFC 9110 |
| 503 | Service Unavailable | RFC 9110 |
| 504 | Gateway Timeout | RFC 9110 |
| 505 | HTTP Version Not Supported | RFC 9110 |
| 506 | Variant Also Negotiates | RFC 2295 |
| 507 | Insufficient Storage | RFC 4918 (WebDAV) |
| 508 | Loop Detected | RFC 5842 (WebDAV) |
| 509 | Bandwidth Limit Exceeded | Not registered: sent by some web hosts when an account has used up its bandwidth allowance |
| 510 | Not Extended | RFC 2774, now obsolete |
| 511 | Network Authentication Required | RFC 6585 |
| 520 | Web Server Returns an Unknown Error | Cloudflare, not registered |
| 521 | Web Server Is Down | Cloudflare, not registered |
| 522 | Connection Timed Out | Cloudflare, not registered |
| 523 | Origin Is Unreachable | Cloudflare, not registered |
| 524 | A Timeout Occurred | Cloudflare, not registered |
| 525 | SSL Handshake Failed | Cloudflare, not registered |
| 526 | Invalid SSL Certificate | Cloudflare, not registered |
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
- Read the exact code first: it identifies the layer, and the layer determines where to look.
- Check whether the error is in your application log or only in the proxy's — that alone splits the search in half.
- Establish whether it affects all requests or a subset, which distinguishes a total failure from a partial one.
- Correlate the start time against deploys, configuration changes and dependency incidents.
- 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.