5xx vs 4xx Errors: Understanding API Health Through Status Codes

Not all API errors are equal. A 404 means a client requested something that does not exist. A 500 means your server broke. Treating these identically in your error rate metric obscures the real health of your API and leads to misplaced engineering priorities. Understanding the difference is foundational to meaningful monitoring.

The Difference Between 4xx and 5xx

4xx errors are client errors — the request was malformed, the resource was not found, authentication failed, or a rate limit was hit. These are generally expected behaviour for a well-functioning API and are often intentional by design. 5xx errors are server errors — your code threw an unhandled exception, your database timed out, or your service crashed. These are always undesirable and always warrant investigation.

Common 4xx Codes and What They Signal

• 400 Bad Request — the request body or parameters were malformed or missing required fields
• 401 Unauthorized — the request lacked valid authentication credentials
• 403 Forbidden — authenticated but not permitted to access the resource
• 404 Not Found — the requested resource does not exist at this path
• 422 Unprocessable Entity — the request was well-formed but semantically invalid
• 429 Too Many Requests — the client has exceeded its rate limit

Common 5xx Codes and What They Signal

• 500 Internal Server Error — an unhandled exception occurred in your application code
• 502 Bad Gateway — an upstream service your API depends on returned an invalid response
• 503 Service Unavailable — your service is overloaded, deploying, or down
• 504 Gateway Timeout — an upstream service took too long to respond

Why Your Single Error Rate Is Probably Wrong

Many monitoring tools compute a single error rate: all errors divided by total requests. But a high 404 rate on a REST API is completely normal — clients probe endpoints, integrations use wrong paths, bots crawl your API. Including these in your health signal makes your 'error rate' almost meaningless. A 5% error rate that is entirely 401s and 404s is a completely healthy API. A 1% error rate that is entirely 500s is a critical problem.

Building a Meaningful Health Error Rate

The solution is to define a health error rate that excludes expected status codes for your specific application. For many APIs, this means excluding 401, 403, 404, 422, and 429 from the error count entirely. Track raw 5xx rates separately as a direct measure of server-side failure. This separation makes each metric immediately actionable.