500 vs 503
Internal Server Error vs Service Unavailable
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.
| 💥500 | 🔧503 | |
|---|---|---|
| Name | Internal Server Error | Service Unavailable |
| Category | 5xxServer Error | 5xxServer Error |
| Description | The server has encountered a situation it doesn't know how to handle. | The server is not ready to handle the request, often due to maintenance or overloading. |
| When to Use |
|
|
| Common Causes |
|
|
The server has encountered a situation it doesn't know how to handle.
- Unexpected server error with no more specific 5xx code applicable
- Unhandled exceptions or crashes in your application
- Generic catch-all for server-side failures
- Unhandled exception in code
- Database connection failed
- Server misconfiguration
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