401 vs 403 vs 404: The Status Code Mistakes That Break APIs
Originally published at ipcalcplus.com . Every API review I've ever done contains at least one of these bugs: a login failure that returns 500, a rate limit that returns 400, a "resource not found" that returns 403 for security reasons and confuses every client developer for the next two years. Status codes are the API's contract with its clients. Break the contract and your consumers write…
APIs are contracts with their clients. Break the contract and clients write defensive code around bugs, which then break when the bug is fixed. This guide explains the status codes that truly matter, focusing on the distinctions often misunderstood.
The two-digit number in HTTP status codes indicates who caused the problem. Codes in the 2xx range mean success, while 3xx means the client should go somewhere else, 4xx means the client broke it, and 5xx means the server broke it. The most critical distinction within 4xx is between 401 and 403.
A 401 Unauthorized indicates the server doesn't know who you are, while a 403 Forbidden means you're authenticated but not allowed to access the resource. Returning a 403 for missing credentials confuses clients, making it hard to determine whether they need to log in or are simply not permitted. A notable exception is when APIs return 404 for resources that shouldn't be accessible, rather than 403, to avoid revealing valid IDs.
The 404 Not Found code is essential but often misused. A 410 Gone means the resource once existed and was deliberately removed, causing search engines to deindex it faster. When moving URLs permanently, use 301 or 308 instead of 404 to preserve search traffic. The distinction between 301 and 302 redirects is crucial, as 301 transfers ranking to the new URL, while 302 does not.
For asynchronous operations, use 202 Accepted to indicate the request was received and is being processed, but not yet completed. Return 204 No Content for successful operations with no meaningful body, such as DELETE requests. This prevents clients from expecting a response body when none is needed.
Incorporate appropriate error codes like 429 Too Many Requests for rate limiting, 422 Unprocessable Entity for invalid data, and 451 Unavailable For Legal Reasons for content removed due to legal reasons. When the server lies, check the 5xx series: 502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout. Each has distinct implications, with 502/504 indicating issues with the proxy and 503 signaling the server is refusing access intentionally.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
