SumitM sparks API 404 debate
What happened
- A post by X user SumitM revived a familiar software design argument: whether `GET /orders` should return `404 Not Found` when no rows match, or `200 OK` with an empty array. - The split was over what the URL represents. If `/orders` is a collection that exists, many engineers treat “no matches” as `[]`; `404` fits a missing resource like `/orders/123`. - The argument maps to long-running HTTP guidance that separates successful empty results from missing resources, and teams keep revisiting it when standardizing API contracts. (rfc-editor.org)
Why it matters
An empty API response set off a bigger argument about what a URL means. A thread around SumitM’s `GET /orders` example reopened the old split between `404 Not Found` and `200 OK` with `[]`. (rfc-editor.org) (stackoverflow.com) The core question is simple: if a client asks for orders and there are none, did the request fail, or did it succeed with zero results? HTTP treats `200` as a successful request and `404` as a missing target resource. (developer.mozilla.org 1) (developer.mozilla.org 2) That distinction usually turns on the shape of the endpoint. Engineers often reserve `404` for a missing single resource like `/orders/123`, while a collection like `/orders` can still exist even when it currently contains zero items. (stackoverflow.com 1) (stackoverflow.com 2) HTTP’s current semantics, published in RFC 9110, define `404 Not Found` around the target resource not being found, not around a successful query returning no members. That is why many API style guides land on `200 OK` plus an empty list for filtered collection reads. (rfc-editor.org) (apihandyman.io) Some teams also consider `204 No Content`, which means the request succeeded and there is no response body. In practice, many developers avoid it for list endpoints because clients then need special handling instead of always parsing the same JSON shape. (developer.mozilla.org) (apihandyman.io) That is where the debate turns from protocol theory into team operations. A stable contract like `200` with `[]` lets front ends, mobile apps, and SDKs treat “no results” as ordinary data instead of an exception path. (apihandyman.io) (stackoverflow.com) Real systems still get this wrong. In February 2026, the RoboSats project logged an issue because `/api/book` returned `404` when there were no orders, and the proposed fix changed that behavior to `200` with an empty list plus a regression test. (github.com) The argument keeps resurfacing because the status code is doing two jobs at once: telling clients whether the endpoint exists and whether the query found data. Teams that separate those ideas usually end up with fewer ambiguous failure modes in production. (rfc-editor.org) (w3tutorials.net) So the SumitM prompt was less about one endpoint than about contract discipline. Once a team decides what `/orders` means, the status code choice stops being a debate and starts being a rule. (rfc-editor.org) (apihandyman.io)
Key numbers
- A post by X user SumitM revived a familiar software design argument: whether GET /orders should return 404 Not Found when no rows match, or 200 OK with an empty array.
- If /orders is a collection that exists, many engineers treat “no matches” as []; 404 fits a missing resource like /orders/123.
- A thread around SumitM’s GET /orders example reopened the old split between 404 Not Found and 200 OK with [].
- HTTP treats 200 as a successful request and 404 as a missing target resource.
What happens next
- HTTP treats 200 as a successful request and 404 as a missing target resource.
- (stackoverflow.com 1) (stackoverflow.com 2) HTTP’s current semantics, published in RFC 9110, define 404 Not Found around the target resource not being found, not around a successful query returning no members.
Quick answers
What happened in SumitM sparks API 404 debate?
A post by X user SumitM revived a familiar software design argument: whether GET /orders should return 404 Not Found when no rows match, or 200 OK with an empty array. The split was over what the URL represents. If /orders is a collection that exists, many engineers treat “no matches” as []; 404 fits a missing resource like /orders/123. The argument maps to long-running HTTP guidance that separates successful empty results from missing resources, and teams keep revisiting it when standardizing API contracts. (rfc-editor.org)
Why does SumitM sparks API 404 debate matter?
An empty API response set off a bigger argument about what a URL means. A thread around SumitM’s GET /orders example reopened the old split between 404 Not Found and 200 OK with []. (rfc-editor.org) (stackoverflow.com) The core question is simple: if a client asks for orders and there are none, did the request fail, or did it succeed with zero results? HTTP treats 200 as a successful request and 404 as a missing target resource. (developer.mozilla.org 1) (developer.mozilla.org 2) That distinction usually turns on the shape of the endpoint. Engineers often reserve 404 for a missing single resource like /orders/123, while a collection like /orders can still exist even when it currently contains zero items. (stackoverflow.com 1) (stackoverflow.com 2) HTTP’s current semantics, published in RFC 9110, define 404 Not Found around the target resource not being found, not around a successful query returning no members. That is why many API style guides land on 200 OK plus an empty list for filtered collection reads. (rfc-editor.org) (apihandyman.io) Some teams also consider 204 No Content, which means the request succeeded and there is no response body. In practice, many developers avoid it for list endpoints because clients then need special handling instead of always parsing the same JSON shape. (developer.mozilla.org) (apihandyman.io) That is where the debate turns from protocol theory into team operations. A stable contract like 200 with [] lets front ends, mobile apps, and SDKs treat “no results” as ordinary data instead of an exception path. (apihandyman.io) (stackoverflow.com) Real systems still get this wrong. In February 2026, the RoboSats project logged an issue because /api/book returned 404 when there were no orders, and the proposed fix changed that behavior to 200 with an empty list plus a regression test. (github.com) The argument keeps resurfacing because the status code is doing two jobs at once: telling clients whether the endpoint exists and whether the query found data. Teams that separate those ideas usually end up with fewer ambiguous failure modes in production. (rfc-editor.org) (w3tutorials.net) So the SumitM prompt was less about one endpoint than about contract discipline. Once a team decides what /orders means, the status code choice stops being a debate and starts being a rule. (rfc-editor.org) (apihandyman.io)
