503 vs 502
Service Unavailable vs Bad Gateway
Server Error Troubleshooting
Understanding the difference between 500, 502, and 503
Something broke!
The server encountered an unexpected condition that prevented it from fulfilling the request.
- Unhandled exceptions in code
- Database connection failures
- Misconfigured server settings
Can't reach backend!
The gateway or proxy received an invalid response from the upstream server it tried to access.
- Upstream server is down
- Network connectivity issues
- Backend timeout or crash
Try again later!
The server is temporarily unable to handle requests due to maintenance or overload.
- Scheduled maintenance
- Server overload/too many requests
- Resource exhaustion
- Application code throws an exception
- Database query fails unexpectedly
- Critical configuration is missing
- Generic error with no specific cause
- Reverse proxy can't reach backend
- Load balancer gets invalid response
- API gateway connection fails
- Upstream server returns malformed data
- Server is in maintenance mode
- Too many concurrent connections
- Rate limit temporarily exceeded
- Include
Retry-Afterheader
500 means the server itself has a problem. 502 means the server is working but can't connect to its backend. 503 means the server is working but deliberately refusing requests. If you're using a reverse proxy (nginx, load balancer), you'll likely see 502. If your app code crashes, that's a 500. If you're deploying or overwhelmed with traffic, send 503.
| 🔧503 | 🌉502 | |
|---|---|---|
| Name | Service Unavailable | Bad Gateway |
| Category | 5xxServer Error | 5xxServer Error |
| Description | The server is not ready to handle the request, often due to maintenance or overloading. | The server was acting as a gateway and received an invalid response from the upstream server. |
| When to Use |
|
|
| Common Causes |
|
|
The server is not ready to handle the request, often due to maintenance or overloading.
- Server is temporarily overloaded and can't handle requests
- Planned maintenance window
- Include Retry-After header to indicate when to try again
- Server maintenance
- Server overloaded
- Temporary outage
The server was acting as a gateway and received an invalid response from the upstream server.
- Proxy/gateway received invalid response from upstream server
- Backend server returned malformed data or crashed mid-response
- Use when your server is a proxy and upstream failed
- Upstream server is down
- Proxy received invalid response
- Backend server crashed