API Error Codes: 404 vs 451 Explained

Most APIs treat "record not found" as a single case with a single status code. That is usually fine, until the dataset also has to support the right to erasure under privacy law, at which point conflating two genuinely different situations under one status code starts actively misleading callers.

A 404 should mean: this specific record has not been indexed yet, or the identifier does not match anything we hold. It is worth retrying later, or trying a different identifier for the same target. A 451 should mean something categorically different: this record existed, was withdrawn under a legal erasure request, and will not come back for any identifier pointing at that same person.

A caller should be able to switch on a stable code field rather than parsing the human-readable message, since the wording of that message can change at any time without warning:

A client that treats every non-2xx response the same way and retries everything will eventually hammer a 451 endpoint indefinitely for a record that will never return, wasting calls and, more importantly, repeatedly re-requesting data about someone who specifically asked for it to be removed. Coding against the specific status code, not just "success or failure," is the only way to build a retry policy that behaves correctly for both cases.