r/Backend • u/ClickOk5811 • 12h ago
Client retries a DELETE after a timeout. Second call: 404, 204 or 410?
A small API design question where I keep seeing different answers.
A client sends DELETE /orders/42. The server deletes the order and starts sending the response, but the connection drops and the client times out. The client doesn’t know whether it worked, so it retries the same request. This time the order doesn’t exist anymore.
What should the second call return?
A. 404 Not Found
Literally true: the resource isn’t there. Simple to implement and what most frameworks do by default. The downside is that the client sees an error for something that effectively succeeded, so it has to treat 404 on a retry as success.
B. 204 No Content (same as the first call)
Makes the retry look identical to the original. The client never needs special handling. The downside is that you also return 204 for ids that never existed, which can hide typos and bugs on the client side.
C. 410 Gone
Says “this existed and was removed on purpose”, which is more informative than 404. The downside is that you need to remember what used to exist, so you need a tombstone or a soft delete, and that’s more state than many services want.
My understanding is that DELETE is meant to be idempotent in the sense that the server state ends up the same after one call or ten, and that the response status doesn’t have to be the same each time. So A is technically fine. But “technically fine” and “pleasant to use” aren’t the same thing.
Where I lean right now is B for internal APIs, where clients are retrying automatically, and A for public ones, where I’d rather surface mistakes. But I don’t feel strongly about it, and I can see C being worth the extra state if you already keep audit records.
Which one do you pick, and does it change when the clients are automated retriers rather than people poking at an API?