REST API - What HTTP code should be returned when resource is not in a state required to complete the operation?

Question

Our API accepts PUT requests in order to change status of resources. Think of this as a state machine. Client can specify the target state of the resource via PUT request but it is possible that the resource is not in a state from where it can go into the target state specified by the client. What HTTP code should we return in this instance? I am thinking 409 Conflict with more details in the response body using a structured error describing what went wrong.

Has anyone experienced this and modelled it differently?

Answer 1

I think 409 is a good choice there if the conflicted state was achieved by another client sending in a PUT i.e.

1. A does a GET
2. B does a GET
3. B does a PUT
4. state is now different
5. A tries to do a PUT but the new state is not possible so A gets a 409.

This only works if the server can determine the bad state transition, either from FSM transitions that are possible or from some code you send in with the request to keep ordering.

The other option would be to use PATCH where you send a delta, how to get from state 1 to state 2 with the http request. This means the server can check if the resource is in state 1 otherwise it can not apply the update. This makes this error path much more explicit to the client.