REST API best HTTP Status response for illegal operation

Question

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?

Answer 1

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.

Answer 2

I think you should use a 403 Forbidden here.

From the HTTP specification:

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. (...)

As you are refusing to change the value of "country", this is the status code you want to return. The client is not authorized to change the resource's country.

409 Conflict is not appropriate in this case. The 409 status is to be used when for instance somebody sends a request to update a resource, but their version of the resource is outdated because the resource has been modified in the meantime. In other words, there is a conflict between the client's data and the data on the server. This has nothing to do with allowing certain properties of the resource to be changed.

The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body SHOULD include enough information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required.

Conflicts are most likely to occur in response to a PUT request. For example, if versioning were being used and the entity being PUT included changes to a resource which conflict with those made by an earlier (third-party) request, the server might use the 409 response to indicate that it can't complete the request. In this case, the response entity would likely contain a list of the differences between the two versions in a format defined by the response Content-Type.

(emphasis mine)