HTTP Status Codes in REST API Design: Semantics, Idempotency & RFC 9457

Standardized under IETF RFC 9110 (HTTP Semantics), HTTP status codes serve as the global signaling vocabulary coordinating communication among web clients, API gateways, reverse proxies, and CDN edge caches. In RESTful API architecture, a status code conveys far more than binary success or failure: it communicates whether a response may be cached, whether an automatic retry is safe, and what corrective action a client must take.

The widespread anti-pattern of wrapping all application responses inside an HTTP 200 OK with custom error payloads in the JSON body degrades systems: it breaks standard browser error handling, renders CDN edge caching policies useless, and blinds infrastructure observability tools.

• 1xx (Informational): Request received, continuing process (e.g., 101 Switching Protocols during WebSocket upgrades).
• 2xx (Successful): The client request was successfully received, understood, and accepted (200 OK for general reads, 201 Created with a Location header, 204 No Content for successful deletes or updates).
• 3xx (Redirection): Further action must be taken by the user agent to fulfill the request.
• 4xx (Client Error): The request contains invalid syntax, missing authentication, or points to resources that cannot be fulfilled due to client-side issues.
• 5xx (Server Error): The server failed to fulfill an apparently valid request due to internal defects, unhandled exceptions, or upstream infrastructure outages.

1. 401 Unauthorized vs. 403 Forbidden:
   • 401 Unauthorized: Semantically means "Unauthenticated". The user has provided no credentials or invalid tokens. RFC 9110 requires the server to include a WWW-Authenticate response header detailing authentication challenges.
   • 403 Forbidden: The user is authenticated and their identity is verified, but they lack authorization (permissions) to access the specified resource. Retrying with identical credentials will not change the outcome.
2. 404 Not Found vs. 410 Gone:
   • 404 Not Found: No current representation exists for the target URI. Search engine crawlers interpret this as potentially transient and will re-crawl later.
   • 410 Gone: Explicitly signifies that the resource once existed but has been permanently deleted. Search engine indexing bots de-index 410 URLs substantially faster than 404s.
3. 301 Moved Permanently vs. 308 Permanent Redirect:
   • Historically, many user agents erroneously rewritten HTTP POST requests to GET requests when following a 301 redirect.
   • 308 Permanent Redirect guarantees that the HTTP request method and body remain unaltered across the redirect hop.

Ratified in 2023 to obsolete RFC 7807, RFC 9457 standardizes error responses for HTTP APIs via the application/problem+json media type. It defines a structured machine-readable error envelope avoiding proprietary divergent schemas:

{
  "type": "https://api.devutils.run/errors/insufficient-balance",
  "title": "Insufficient Account Balance",
  "status": 403,
  "detail": "Your current balance is 30 credits, but this operation requires 50 credits.",
  "instance": "/account/12345/transactions/abc",
  "balance": 30,
  "required": 50
}

• Safe Methods (GET, HEAD, OPTIONS): Read-only operations that do not mutate server state.
• Idempotent Methods (GET, PUT, DELETE, HEAD): Executing identical requests multiple times produces the exact same server state as a single execution.
• Non-Idempotent Methods (POST, PATCH): Multiple calls can create duplicate charges or redundant resources.

When client HTTP clients implement automated exponential backoff retry algorithms to handle network hiccups, they must restrict retries strictly to idempotent methods unless an explicit idempotency key header (Idempotency-Key) is coordinated with the backend.