In REST API development, handling operations where data is absent or deleted often raises questions about status code semantics. Two frequently compared status codes in this domain are HTTP 404 Not Found and HTTP 204 No Content.

While developers sometimes encounter both in scenarios involving missing data, their fundamental semantics belong to completely different status classes.

Core distinction: error versus bodyless success

  • HTTP 404 Not Found (4xx Client Error): The server cannot find the requested resource representation. It signals an error condition for a missing URI or entity.
  • HTTP 204 No Content (2xx Success): The server successfully executed the request, and there is no additional content to send in the response body.

What HTTP 404 Not Found means

According to RFC 9110, an HTTP 404 status indicates that the origin server did not find a current representation for the target resource.

When fetching an individual resource by ID (GET /v1/users/usr_99999), if that user does not exist, status 404 is the standard HTTP response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error": "not_found", "message": "User usr_99999 was not found."}

What HTTP 204 No Content means

An HTTP 204 status indicates that the server has fulfilled the request and that there is no entity body to return in the response.

By specification, a 204 response MUST NOT include a message body. Common uses include:

  • DELETE /v1/items/123: The item was successfully deleted from the database.
  • PUT /v1/users/123/preferences: The settings were saved, and the client does not need an updated representation returned.
HTTP/1.1 204 No Content
Date: Thu, 10 Sep 2026 10:00:00 GMT

Single resources vs. empty collections vs. deletions

API designers navigate three distinct patterns:

1. Single Resource Lookups (GET /items/123)

If item 123 does not exist, return 404 Not Found. Returning 204 for a missing resource lookup is anti-pattern because GET is an inquiry for representation; missing data is an error in resource addressing.

2. Collection Queries (GET /items?category=books)

If a search query matches zero records, return 200 OK with an empty collection payload [] (e.g., {"data": [], "total": 0}). The collection resource itself exists, even if it contains zero elements.

3. Deletion Operations (DELETE /items/123)

  • Idempotent Pattern (Common): Returning 204 No Content whether the resource was just deleted or was already absent. The desired end state (resource does not exist) is fulfilled.
  • Strict Pattern: Returning 204 No Content on the first deletion, and 404 Not Found on subsequent deletions if the resource was already removed.

Side-by-side comparison table

Feature HTTP 404 Not Found HTTP 204 No Content
Status Class 4xx (Client Error) 2xx (Success)
Response Body Allowed and recommended (JSON error) Forbidden by HTTP specification
GET Missing Item Correct standard response Inappropriate
GET Empty Search Avoid (use 200 with []) Avoid (use 200 with [])
DELETE Item Used in strict deletion models Standard for idempotent deletion

How to choose the right status in REST API design

  1. For resource lookups (GET by ID): Always use 404 Not Found when the record does not exist.
  2. For list/search queries: Always use 200 OK with an empty JSON array [].
  3. For deletions and updates without body: Use 204 No Content.

What to check before changing code

  1. Does your client application check response status codes before attempting to parse JSON bodies? (Parsing a 204 response as JSON will fail because it has no body).
  2. Are DELETE endpoints designed for idempotent 204 responses or strict 404 responses?
  3. Does your API return consistent 404 error payloads across all single-item endpoints?

Key takeaway

Use HTTP 404 Not Found when a requested resource does not exist. Use HTTP 204 No Content when an action succeeded but requires no response body. Never use 204 in place of 404 for failed single-resource lookups.