HTTP 404 Not Found indicates that the requested resource could not be found. It assigns responsibility to the client-side request when a resource identified by a path parameter does not exist. section 4.5.10 section 4.5.8
Use 404 when:
- A request targets a nonexistent resource, such as GET /products/{productReference} for an unknown product. section 4.5.8
- A DELETE operation targets a resource that does not exist; the response should use 404 rather than falsely reporting success. section 3.1.3
- The API must avoid disclosing whether a protected resource exists, such as an account outside the caller’s permitted view. section 12.10.2
Missing product
A consumer sends DELETE /products/123 when product 123 does not exist. A compliant response is 404 Not Found. By contrast, 204 No Content means the product exists and the operation intentionally returns no data; 400 Bad Request is appropriate for missing or invalid input. section 4.5.10 section 3.1.3
Listing 6.11 Response without a body
...
paths:
/products/{productReference}:
summary: Product
...
delete:
summary: Remove a product from the catalog
responses:
"204":
description: Product removed
#1
"404":
description: No product found
content: #2
application/json:
schema:
description: Error info.
An OpenAPI response definition gives the 404 response an error description and JSON content, unlike a 204 response without a body. section 6.8.2
Figure 12.12 The “Read an account” operation returns “403” if the consumer doesn’t have the proper scope or if the end user is a bank advisor who doesn’t manage the account. It also returns “404” if the end user is an account owner who does not own the account.
A permission example shows when 404 conceals a protected account and when 403 Forbidden can safely communicate an access problem. section 12.10.2
