Course contentsShow
← Software Engineering
Lesson 772 of 1,93324. REST API DesignFree lesson

Server Error Codes: 5xx Range

Communicating server failures: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable.

Server Error Codes: 5xx Range

What you'll learn: How REST APIs use 5xx status codes to signal that something went wrong on the server side, not because of the client's request.


When the Server Is at Fault

Unlike 4xx errors (which mean you made a mistake in your request), 5xx errors indicate the server failed to fulfill a valid request. Think of it like ordering food at a restaurant: a 4xx is when you ask for something not on the menu, but a 5xx is when the kitchen catches fire.

These errors tell the client: "Your request was fine, but we couldn't process it due to a problem on our end."


The Three Most Common Server Errors

500 Internal Server Error
The generic "something broke" response. The server encountered an unexpected condition—maybe an unhandled exception, a null pointer error, or a bug in the code. It's like saying "Sorry, we don't know exactly what went wrong, but it's our fault."

502 Bad Gateway
The server acted as a gateway or proxy and received an invalid response from an upstream server. Imagine your API server tried to call another service (like a database or third-party API), but that service sent back garbage. Your server returns 502 to say "I'm okay, but the service I depend on isn't."

503 Service Unavailable
The server is temporarily unable to handle requests, often due to maintenance or overload. This is the polite "we're closed for now, try again later" message. Unlike 500, this suggests the problem is temporary and might include a Retry-After header.


Key Takeaway: 5xx status codes signal server-side failures—500 for unexpected errors, 502 when dependent services fail, and 503 when the server is temporarily unavailable. These tell clients the fault lies with the server, not their request.