Search code examples
resthttp-status-codes

REST API best HTTP Status response for illegal operation


I'm creating a REST API in PHP.

When the client may try to perform an action, which is unavailable, for example, it tries to change a property of the resource which is not passable: for example, tries to change the value of the "country" property to "Julius Caesar":

  1. What HTTP status code should I send back with the response? I'm speculating between 403 and 409.
  2. I don't know if 403 Forbidden is only related to user permissions or can I use for this purpose?
  3. In what situation should I use 409 Conflict?
  4. To summarize what is the proper HTTP response status to an illegal operation?

Solution

  • In this situation, I usually opt for a 400 Bad Request. I'm not sure if a more specific 400 range status code would fit better, however I would not use 403. For me, a 403 is security related, and should not be used for request payload validation errors.

    As for 409 Conflict, I usually use this if the request is valid, but the state change is somehow illegal. However, I have seen it used in other contexts as well.

    In the end, as long as you are consistent across your API (and document the meaning of the return status codes), you have some flexibility to decide how you want to express the error.