Use 401 Unauthorized when valid authentication credentials for the requested resource are missing or invalid; include a WWW-Authenticate challenge. Use 403 Forbidden when the server understands the request but refuses it, including because the requester lacks permission. Use 404 Not Found when no current representation exists—or when policy deliberately hides that a forbidden resource exists.
How 401, 403, and 404 differ
These codes describe different outcomes from the server’s perspective. The distinction is not simply “logged out,” “not allowed,” and “missing”: 401 is tied to authentication, 403 is a refusal, and 404 concerns whether a representation is found or disclosed. These semantics are specified in RFC 9110, HTTP Semantics, published by the IETF in June 2022.
As an Amazon Associate I earn from qualifying purchases.
| Status | Authentication and authorization | Resource and disclosure | Practical meaning |
|---|---|---|---|
| 401 Unauthorized | Valid authentication credentials for the target resource are absent or lacking. | Does not itself say whether the resource exists. | The request was not applied because the client needs applicable authentication credentials. The response must include a WWW-Authenticate challenge. |
| 403 Forbidden | The server refuses the request; supplied credentials may be valid but insufficient, or the refusal may have another cause. | Does not itself say whether the resource exists. | The server understood the request but will not fulfill it. Retrying with the same credentials is not a useful default. |
| 404 Not Found | Does not establish whether the requester is authenticated or authorized. | No current representation was found, or the server is deliberately concealing a forbidden resource’s existence. | The client cannot infer from 404 alone whether the resource never existed, is temporarily unavailable, or is being hidden. |
Which response should an API return?
Choose the status from the condition the server has determined, rather than using one code as a generic error. In particular, decide authentication first, then authorization, then whether the resource is present and whether revealing it is acceptable.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Credentials absent, invalid, or incomplete for the authentication scheme: return 401 and include an applicable
WWW-Authenticatechallenge. - The request is understood, but policy denies the operation: return 403. This includes cases where the user is authenticated but lacks the necessary permission.
- There is no current representation for the target: return 404.
- The resource is forbidden and its existence should not be disclosed: a deliberate 404 response is permitted. Apply this as a consistent information-disclosure policy, not as a replacement for access checks.
- The server knows the resource is likely permanently gone: prefer 410 Gone over 404.
Common status-code mistakes
Returning 403 when the client needs to authenticate
If the server is asking the client to provide or correct authentication credentials, use 401. A 403 communicates refusal; it does not mean simply that the client is unauthenticated.
#1 Best Overall
Sending 401 without a challenge
RFC 9110 requires a server generating 401 to send at least one WWW-Authenticate challenge applicable to the target resource. Returning 401 without that header omits a required part of the response.
Treating 403 as a universal permission error
403 means the server understood the request and refuses to fulfill it. Insufficient credentials are one possible reason, but the refusal can be unrelated to credentials. Clients should not automatically retry with the same credentials.
Rank #2
- Used Book in Good Condition
Assuming 404 proves permanent absence
A 404 can conceal a forbidden resource, and it does not tell the client whether the absence is temporary. When the server knows the condition is likely permanent, RFC 9110 prefers 410 Gone.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Make the API error contract more informative than the status alone
A three-digit status is not always enough to explain an application failure. AWS’s Amazon S3 error-response guidance says its service-specific error code is more informative than the HTTP status and recommends using that code for handling and reporting S3 errors. That is an S3-specific contract; other APIs should document their own stable error details rather than assume the same fields or behavior.
Define the response as a unit: status, headers, and body. Amazon API Gateway documentation describes a method response as defining expected status codes, headers, and body models. Amazon Prime API error guidance uses structured error code and message fields, cautions clients against relying on undocumented response details, and notes that additional status codes may be supported in future.
Quick Recap
Best Value
- Document which status codes each operation can return and under what conditions.
- Document the response headers and the meaning of any machine-readable application error code and human-readable message.
- Specify retry guidance when the service promises it; clients should not infer retry behavior from these three statuses alone.
- Have clients rely on documented fields and handle unfamiliar status codes safely, rather than assuming the current list is exhaustive.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
