HTTP status codes 404, 500, 502, and 503 explained
How the code classes narrow down an investigation, the real causes behind common errors, and the difference between 401 and 403, 502 and 504.
The first digit halves the search
An HTTP status code has three digits and the first one gives the class.
2xx is success, 3xx is redirection, 4xx is a problem with the request, and 5xx is a problem on the server. During an incident this division matters because it decides where to look.
A 4xx means you should examine the address, headers, body, and credentials the client sent. A 5xx means the request arrived intact, so the server logs and infrastructure are the place to start. Respecting that split alone saves a great deal of wasted searching.
404, 403, and 401
404 Not Found means the requested resource does not exist. Typical causes are a typo, deleted data, or a missing route, and for static files it can mean the file never made it into the deployment.
401 Unauthorized, despite the name, is about authentication. The token is missing, expired, or malformed, so the server cannot tell who is calling. Logging in or refreshing the token resolves it.
403 Forbidden is about authorization. The caller is identified but lacks permission for that resource, so logging in again changes nothing and the permission itself must be granted.
Note that some services deliberately return 404 instead of 403 to avoid revealing whether a resource exists at all.
For 5xx, where it happened matters
500 Internal Server Error means an unhandled exception in application code, and there is usually a stack trace waiting in the server log.
502 Bad Gateway and 504 Gateway Timeout are different in nature. Both come from a reverse proxy or load balancer rather than the application itself.
A 502 means the upstream server returned an invalid response or could not be reached: a dead application process, a wrong port, or a gap during deployment.
A 504 means the connection succeeded but no response arrived in time, pointing at a heavy query, a slow external API, or a loop. Simply raising the proxy timeout treats the symptom, so measure the actual processing time first.
503 Service Unavailable means the server is temporarily unable to handle the request, whether for maintenance or overload, and can advise a Retry-After value.
Choosing codes when designing an API
When building your own API, these conventions hold up well.
- Return 204 No Content when the call succeeded but there is nothing to send back.
- Return 201 Created with a Location header when a resource was created.
- Use 400 for malformed input, 401 for missing authentication, 403 for insufficient permission, and 404 for a missing target.
- Use 422 Unprocessable Entity when input parses correctly but violates a business rule.
- Pair 429 Too Many Requests with a Retry-After header when rate limiting.
- Avoid returning 200 with an error in the body: monitoring and caches will treat it as a healthy response.