HTTP status quote when a resource can't be inserted but could be fixed by the client

Question

I have a resource I want to insert via POST; say a reservation. In some cases, the server can't insert the given object, but needs to give feedback to the user, what needs to change in order to be able to insert it. For example if you send a reservation with the following content:

{
  "start": "2020-09-14T15:00:00Z",
  "end": "2020-09-14T15:00:00Z",
  "memberId": 5,
  "seat": "A5",
}

If the server sees that seat A5 is already occupied, but wants to return a list of seats that would be free for that time range, what would I use?

409 Conflict seems to be somewhat like what I want, because in its specification you can tell the user what's wrong. But I'm not sure if this would count as a conflict.

Answer 1

409 Conflict seems to be somewhat like what I want, because in its specification you can tell the user what's wrong.

All 4xx response codes permit you to tell the user what is wrong - see RFC 7231

the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.

That said, 409 is fine.

Another reasonable alternative to consider would be 403 Forbidden.

The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it.

The normative text for these two codes is different, but if you review the specification there's not a lot of indication that general purpose components treat them differently - they are both not cachable, neither makes any significant change to the semantics of the response headers, and so on.

Given that the effects are the same, you are largely choosing between concerns like "what do you want to see in the access logs?", "which general purpose alarm do we want to raise", and so on.

Since your operators probably don't want these signals getting crossed with corrupted http requests (400) and security penetration attempts (403), choosing a different code for requests that conflict with your internal domain logic will make their lives easier.