Search code examples
http-1.1http-status-code-409

Is it allowed to use the 409 Conflict status code to prevent some fields from being updated in a HTTP PUT request


While working on an (json) REST API, I came upon the situation that we have a representation of a user resource where I wanted to prevent a field (email) to be overridden within a PUT. If I understand correctly, then a PUT should contain the entire representation of the resource to replace the old one.

So for example, when fetching a user from the API (Some headers left out for simplicity):

> GET /user/123 HTTP/1.1
> Host: example.com
> Authorization: Bearer XXXXX
> Accept: application/json

< HTTP/1.1 200 OK
< Content-Type: application/json
< 
< { "name": "John Smiht"
< , "email": "[email protected]"
< }

And you'd want to fix the typo in John Smiths name, you'd do:

> PUT /user/123 HTTP/1.1
> Host: example.com
> Content-Type: application/json
> 
> { "name": "John Smith"
> , "email": "[email protected]"
> }

< HTTP/1.1 201 No Content

Now, if someone were to put a different e-mail address, am I allowed to use a 409 to indicate the request was not processed?

> PUT /user/123 HTTP/1.1
> Host: example.com
> Content-Type: application/json
> 
> { "name": "John Smith"
> , "email": "[email protected]"
> }

< HTTP/1.1 409 Conflict
< Content-Type: application/json
<
< { "errorNumber": "XXX"
< , "errorMessage": "Not allowed to change e-mail address this way"
< }

According to https://www.rfc-editor.org/rfc/rfc2616

  • A 400 Bad Request indicates malformed syntax (which this isn't)
  • A 403 Forbidden could be used, but it seems to me that it is more about access to the entire resource, not part of it
  • A 409 Conflict seems to be about a technical reason for not being able to fulfil the request, and not about having privileges to do something.

So, my question is: which status code should I use?


Edit: in light of the accepted answer; the response would become

> PUT /user/123 HTTP/1.1
> Host: example.com
> Content-Type: application/json
> 
> { "name": "John Smith"
> , "email": "[email protected]"
> }

< HTTP/1.1 403 Forbidden
< Content-Type: application/json
<
< { "errorNumber": "XXX"
< , "errorMessage": "Not allowed to change e-mail address this way"
< }

Solution

  • I'd say if the user didn't have the right to change e-mail address 403 would be the right code as the server understood the user but refuse to act on it. (Usually it means missing scope / privileges)