I am trying to implement some PATCH requests in our software(following https://www.rfc-editor.org/rfc/rfc7396). The resources have some fields which must not be modified, so I am thinking to return some error status code when such fields appear in HTTP JSON request body. 400 seems a bit too generic (I am using it for validation errors e.g. email format and the like). Perhaps there is some other status code used in such situations?
2 Answers
There's a code for that . . . 8-)
403 Forbidden
The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason
https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
Furthermore, 403 is suitable even if there are no credential problems. This is explained in RFC7231 Section 6.5.3:
a request might be forbidden for reasons unrelated to the credentials
-
As @VoiceOfUnreason says, I too have the feeling that 403 is used more to communicate a problem with credentials. For example, Wkipedia says "HTTP 403 is a standard HTTP status code communicated to clients by an HTTP server to indicate that the server understood the request, but will not fulfill it for some reason related to authorization", though the subcodes used by IIS found on the same wikipedia page actually support your point of view in my opinion. Commented Aug 24, 2018 at 9:50
-
Regardless of how anybody uses it or what Wikipedia says, 403 means exactly what it's defined as. The quote I posted was directly from the RFC. Commented Apr 24, 2022 at 20:38
RFC 7231 section 8.2 a status code registry, so that's the place to start.
This is clearly a problem with the request; something the client might be able to fix, so an entry from the 4xx class is appropriate.
405 Method Not Allowed is wrong for the case you describe -- a different merge patch document would be accepted by this resource, but not the one that is present.
403 Forbidden is wrong, as it communicates a problem related to credentials, but you are describing a problem with payload.
409 Conflict could be reasonable...
the request could not be completed due to a conflict with the current state of the target resource.
I don't see any reason that the conflict can't be in an immutable part of the "current state".
But I think your best bet is 422 Unprocessable Entity
The 422 (Unprocessable Entity) status code means the server understands the content type of the request entity (hence a 415(Unsupported Media Type) status code is inappropriate), and the syntax of the request entity is correct (thus a 400 (Bad Request) status code is inappropriate) but was unable to process the contained instructions. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.
Another good resource to consider is the HTTP Patch specification. RFC 5789 enumerates a number of reasons that a patch might fail, and what code would be appropriate to use in each context. You can decide for yourself whether you think those distinctions are appropriate in your circumstances.
There may also be more specific errors like "Conflicting State" that could be signaled with this status code, but the more specific error would generally be more helpful.
-
I use 409 for optimistic lock exceptions. 422 is reasonable, I agree. One could think that by now the community would have had reached some consensus after the religious battles over Roy Fielding's thesis.. I mean, with regards to something as basic as this :) But maybe I am "not doing things in the right way" :) One solution which I have seen that people just go with KISS and POST everything (apart from GET and DELETE), this way they at least don't violate some obscure phrase found in some obscure place.. Commented Aug 24, 2018 at 8:51
-
"I use 409 for optimistic lock exceptions." If you are leveraging the conditional request capabilities built into HTTP, the
412 Precondition Failed
would make sense. Commented Aug 24, 2018 at 11:37 -
You are right. To add complexity, though, I found the following nice analysis blog.novatec-gmbh.de/… where the author writes "Even after comparing the received version with the current version – that means after reading the stored record from the database and before updating it – there might be another transaction that changes the record in the very same moment. Therefore it is still possible that an OptimisticLockException occurs. In this case the HTTP status code 409 (Conflict) is returned." :) Commented Aug 24, 2018 at 11:56
-
I don't find Schwörer's argument compelling, and have deep suspicions about status codes that depend on implementation details. But the REST Police aren't going to come after you in either case. Commented Aug 24, 2018 at 12:44
-
"In cases when the server detects a possible conflicting modification and no precondition was defined in the request, the server can return a 409 (Conflict) response." (RFC 5789). I don't promise that the standards, correctly interpreted, supports my claim. Commented Aug 24, 2018 at 12:51