HTTP response code for POST when resource already exists

Question

I'm building a server that allows clients to store objects. Those objects are fully constructed at client side, complete with object IDs that are permanent for the whole lifetime of the object.

I have defined the API so that clients can create or modify objects using PUT:

PUT /objects/{id} HTTP/1.1
...
{json representation of the object}

The {id} is the object ID, so it is part of the Request-URI.

Now, I'm also considering allowing clients to create the object using POST:

POST /objects/ HTTP/1.1
...
{json representation of the object, including ID}

Since POST is meant as "append" operation, I'm not sure what to do in case the object is already there. Should I treat the request as modification request or should I return some error code (which)?

Solution 1

My feeling is 409 Conflict is the most appropriate, however, seldom seen in the wild of course:

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.

Solution 2

According to RFC 7231, a 303 See Other MAY be used If the result of processing a POST would be equivalent to a representation of an existing resource.

Solution 3

It's all about context, and also who is responsible for handling duplicates of requests (server or client or both)

---

If server just point the duplicate, look at 4xx:

• 400 Bad Request - when the server will not process a request because it's obvious client fault
• 409 Conflict - if the server will not process a request, but the reason for that is not the client's fault
• ...

For implicit handling of duplicates, look at 2XX:

• 200 OK
• 201 Created
• ...

if the server is expected to return something, look at 3XX:

• 302 Found
• 303 See Other
• ...

when the server is able to point the existing resource, it implies a redirection.

---

If the above is not enough, it's always a good practice to prepare some error message in the body of the response.

Solution 4

Personally I go with the WebDAV extension 422 Unprocessable Entity.

According to RFC 4918

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.

Solution 5

Late to the game maybe but I stumbled upon this semantics issue while trying to make a REST API.

To expand a little on Wrikken's answer, I think you could use either 409 Conflict or 403 Forbidden depending on the situation - in short, use a 403 error when the user can do absolutely nothing to resolve the conflict and complete the request (e.g. they can't send a DELETE request to explicitly remove the resource), or use 409 if something could possibly be done.

10.4.4 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 for the refusal in the entity. If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.

Nowadays, someone says "403" and a permissions or authentication issue comes to mind, but the spec says that it's basically the server telling the client that it's not going to do it, don't ask it again, and here's why the client shouldn't.

As for PUT vs. POST... POST should be used to create a new instance of a resource when the user has no means to or shouldn't create an identifier for the resource. PUT is used when the resource's identity is known.

9.6 PUT

...

The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI,

it MUST send a 301 (Moved Permanently) response; the user agent MAY then make its own decision regarding whether or not to redirect the request.

View more solutions

Comments

[Green]

As of June 2016 FB blatantly sets 200 on registration when email exists

[Ken]

Github API returns 422 when trying to create a resource (team/repo) with a name that is already in use

[Suncat2000]

It depends if you consider the existence of the object an error or not. If you process the append, 200 or 204 are the most appropriate response codes.

[danday74]

In summary its a toss up between 409 Conflict and 422 Unprocessable Entity - I think the weight of answers here points to 409 though and certainly from a human perspective is more readily understandable

[Cameron Martin]

@Green that will be to prevent account enumeration attacks.

[Anthony O]

I use 409 for this and 422 for bad forms only.

[vmj]

This is an interesting thought, and prompted me to finally read the WebDAV RFC. However, I think the meaning of 422 is that the request and the included entity were syntactically correct but semantically didn't make sense.

[manuel aldana]

why not go for 400 Bad Request? For me this looks a bit like a validation error (you are providing wrong payload with illegal id).

[Wrikken]

400 => "The request could not be understood by the server due to malformed syntax". And the server understands perfectly, but is unable to comply due to a conflict. There is nothing wrong with the request & syntax, only a data problem. A 400 would instantly make me believe the whole mechanism I'm using is flawed, instead of just the data.

[namuol]

@vmj precisely; for instance, GitHub's API spits out 422 for malformed JSON bodies in POST requests.

[awendt]

Malformed JSON is not a syntactically correct entity, so a 422 strikes me as odd...

[gertas]

Ruby on Rails uses 422 for invalid data for years.

[Aviram Netanel]

3xx statuses are meant for redirection

[dactylroot]

"The requested resource resides temporarily under a different URI." from w3.org/Protocols/rfc2616/rfc2616-sec10.html

[alanjds]

IMHO, "307 Temporary Redirect" is the real temporary redirect. "302" is ambiguous, but "FOUND!!" is the really desired message here. The best unambiguous compromise is "303 See Other" on the HTTP semantics. I would go with "303 See Other".

[ygormutti]

Note that the resource referenced by this part of the spec is the collection in which the client is trying to append a new object. If the server accepted the request to change the collection it would lead it to an inconsistent state caused by a previous change in the collection, which is the definition of version conflict. This helped me realize that this answer is probably correct. In this case the server could also include in the response a Link header referencing the existing resource or a hyperlink in the entity body.

[partkyle]

What about an object that has a join table relation? Say we have account, product, and account_product as database tables. I want to add a product to an account, so I would want to post to /account/{id}/product with the product_id. If only one account-product relationship is allowed, what should I return?

[Alfonso Tienda]

Forget the database tables. Let's say a product can only be related to an account... Then it's one to many relationship. So, POST /product/{id} with {'account':account_id}. If you have the max cardinality set to '1' (one to one relationship).... Why are they separated rest objects? An error of cardinality will be just a 400 err. Keep it simple. I hope I understood your question.

[Dennis]

GitHub's API returns a 422 status code when you try to create an already existing resource (e.g. a repository by the same name). The message it returns in the response is "Validation Failed"

[AlexCode]

I just posed this question also and for me the ID is not the technical ID on the database but the something like the company code. In this application a manager user can create companies and has to give them a code. This is the company ID for the user, despite the fact that the DB table also has a technical ID. So in my case I'll return a 409 if the same company code already exist.

[alanjds]

@DavidVartanian Hum... I dont see an error here. The client send a right request, but how to say "Sorry, but what you are trying to create here already exists THERE"? Seems a job for some 3xx. It is not a 4xx for me, as there is no client error.

[David Vartanian]

that's an error!! what's an error for you? The client tried to execute an operation, but it could not finish it due to a specific reason: the entity you are trying to create already exists!

[alanjds]

Who made the mistake? The server or the client?

[alanjds]

I really think that neither. The client had no mistake, so no 4xx here. The server had no mistake, so no 5xx here.

[Martin Kersten]

This is no option due you want to append a certain item which id is already existing. So you try to add something but this is already there. A OK would be only apply if the data set was grown. Append Something -> Ok I appended nothing. Does not fit, I guess.

[Tamer Shlash]

I would not go with this. From the same URL referenced in the answer: "For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions." This is the real meaning of an unprocessable entity, unlike the case when you send completely valid request entity with valid syntax AND semantics, but the only problem is that it conflicts with an existing entity. Actually, if the semantics of the request entity were not valid, there should not be a similar, existing entity at all.

[Harish]

Adding to Tamer comment, if the second request came first, then it would succeed, which will not possible if that was semantically correct. Hence in correct semantics wouldn't apply here.

[alanjds]

@DavidVartanian Thanks for the discussion. Updated the answer towards 409. The client is wrong to ask for impossible stuff, even if it does not know that it is impossible.

[javajavajavajavajava]

@Wrikken That is no longer correct. HTTP 400 was changed in RFC 7231 to mean "the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing)." I'm not saying 400 is correct usage in this case but it could be correct with the new definition of 400.

[Wrikken]

@javajavajavajavajava: still, duplicate data is not a 'client error' in my mind, but that's in the eye of the beholder of course.

[Adrian]

This answer is wrong. 202 means that the server did not find a problem with the request, but chose to process the request after responding. It also means that it expects that the processing to be successful. In our case the server knows that the processing will fail, so 202 is the wrong response.

[Sinaesthetic]

It's not. The intent of the 400 in both definitions is to tell the client to stop trying because the request is bad.

[Sinaesthetic]

An example of 202 would be a queue or subscription. In other words, the result of the request may not be available immediately if you were to query it right this moment.

[Sinaesthetic]

Patch is like PUT but not a complete replacement. It's used to modify a piece of the resource like adding, removing, or modifying a single element of the resource instead of replacing it as a whole.

[Sinaesthetic]

@partkyle Stop using PKs as public IDs!!

[rocketspacer]

Some entities have unique constraints on them, not just the id. Like an account, you can't create an account if user doesn't provide username. And adding an account with no username is obviously impossible

[Alfonso Tienda]

When an entity has an unique constraint, the server must response 409 CONFLICT. I think it's not the point of the question. When you PUT an item and the item already exists (id) you can modify it, but there will be an 409 if you duplicate an Unique constraint.

[Nando]

In my opinion, this might a well be the accepted answer. Though "MAY" indicates a completely optional item, it is the only response code suggested by the official RFC 7231 documentation.

[Seth]

This is the most RESTful answer.

[musicin3d]

My understanding: "status code indicates that the target resource has more than one representation ... information about the alternatives is being provided so that the user (or user agent) can select a preferred representation by redirecting its request to one or more of those identifiers" We are explicitly trying to prevent more than one representation. There are no options. There are no alternatives for the client to choose from. The client should resubmit with a different id. With that said, one should also consider whether unique ids should be generated in the client vs. server.

[Stijn de Witt]

I think 403 Forbidden implies that, even though the user is authenticated, he is not authorized to execute the requested action. I would not use it for validation errors. Example: Not logged in, I attempt to delete something. Server sends me 401 Unauthorized (which is just badly named, should be 401 Unauthenticated). I log in and try again. This time the server checks my permissions, sees i'm not allowed and returns 403 Forbidden. Also see this question.

[dave4jr]

just FYI.. IE does not return response body for a 303, if that matters.

[Sinaesthetic]

I think context is important. For example: returning a 303 implies a redirection to the found resource is needed. That might make sense in a server to server call, but if you were running through a user registration process, it would make no sense at all.

[Michael Scheper]

Sorry, I'm downvoting this. The HTTP 300s are about redirecting, and redirecting to another object which probably has different properties would be very misleading.

[p0lar_bear]

Hm... true. The thought here was jumping right to telling the user that their authorizations make the resource immutable in the OP's use-case - it already exists, you have no permission to do anything to resolve the conflict, don't try creating the resource again.

[Nullius]

You don't have to be sorry. However, if the representation is equivalent to an existing resource, how can it have different properties? And even if it would have, how would a redirect be misleading? The OP says: I'm not sure what to do in case the object is already there. It is in fact the 'same' object. Why would a redirect be misleading? You're talking about another object which in the mind of the OP clearly isn't.

[Michael Scheper]

@Nullius: Quite right; I overlooked that final detail in the question. Apologies.

[Michael Scheper]

@Nullius: SO is not letting me undo my downvote unless the question is edited. May I suggest you clarify that your answer is only appropriate for when the object is already there? I suspect I'm not the only person who overlooked that detail.

[Hagen von Eitzen]

@Tamer Why so? The command "Please create object xy" is syntactically correct. It is semantically correct only if it is possible to create object xy. If object xy already exists, it can no longer be created, hence this is a semantic error.

[Gili]

I return HTTP 409 with a Location header pointing to the existing/conflicting resource.

[maris]

I still believe 409 is appropriate than 400. w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10

[Sinaesthetic]

Semantically, the client is saying "Create this" and the server is responding by saying "Go here instead". The conversation doesn't make any sense. It's almost as if the server is telling the client to "post to this location instead". 300s are more a more appropriate response to a GET request or a POST in the case where the server is responding with "Ok I created it and it's over here"..

[Sinaesthetic]

Semantically, the client is saying "Create this" and the server is responding by saying "Go here instead". The conversation doesn't make any sense. It's almost as if the server is telling the client to "post to this location instead". 300s are more a more appropriate response to a GET request or a POST in the case where the server is responding with "Ok I created it and it's over here".

[Nullius]

@Sinaesthetic: I think it's perfectly fine in some scenario's to let the client know 'hey, this one already exists, you can find it here'. The 'Ok I created it and it's over here' you mentioned, should be provided with the Content-Location header with the 201 Created or 200 Ok status codes. So, if something has been created, only 200 and 201 are valid return codes. This is also clearly stated in the same RFC I linked in my original answer. I agree that 303 might not be a correct answer in all situations or for all business cases. That is also the reason they stress the MAY in the RFC, I guess.

[Grant Gryczan]

According to the spec, it is implied that error 409 cannot be returned by a POST request (when used correctly), as it states that it should be returned when it conflicts with the target resource. Since the target resource has not yet been posted to, it cannot possibly conflict, and thus to reply with 409 Conflict does not make any sense.

[Grant Gryczan]

According to the spec, it is implied that error 409 cannot be returned by a POST request (when used correctly), as it states that it should be returned when it conflicts with the target resource. Since the target resource has not yet been posted to, it cannot possibly conflict, and thus to reply with 409 Conflict does not make any sense.

[Grant Gryczan]

According to the spec, it is implied that error 409 cannot be returned by a POST request (when used correctly), as it states that it should be returned when it conflicts with the target resource. Since the target resource has not yet been posted to, it cannot possibly conflict, and thus to reply with 409 Conflict does not make any sense.

[Grant Gryczan]

According to the spec, it is implied that error 409 cannot be returned by a POST request (when used correctly), as it states that it should be returned when it conflicts with the target resource. Since the target resource has not yet been posted to, it cannot possibly conflict, and thus to reply with 409 Conflict does not make any sense.

[Sinaesthetic]

Debatable imo. If you post to /users then the resource is the collection instead of the individual record /users/{id}

[Grant Gryczan]

It's an error specifically for version control, when there is a conflict between the version of the resource stored and the version of the resource requested. It's very useful for that purpose, for example when the client has cached an old version of the resource and sends a request based on that incorrect version which would no longer be conditionally valid. "In this case, the response representation would likely contain information useful for merging the differences based on the revision history."

[Grant Gryczan]

I do like your suggestion to use PUT though.

[Fernando Ferreira]

As I said, I don't thing this is a error. But I see the point of @martin

[Ray]

@GrantGryczan the collection you're POSTing to is itself a target resource. In this case that would be POST /objects/.

[Grant Gryczan]

It's an error specifically for version control, when there is a conflict between the version of the resource stored and the version of the resource requested. It's very useful for that purpose, for example when the client has cached an old version of the resource and sends a request based on that incorrect version which would no longer be conditionally valid. "In this case, the response representation would likely contain information useful for merging the differences based on the revision history."

[Grant Gryczan]

If the resource is not successfully created, then there is by definition an error.

[dhj]

This is also the code the Auth0 library uses for a case when a User already exists when you are trying to register.

[laaksom]

Issuing a 409 instead of a generic 400 also lets a malicious user find emails that already exist in the system.

[Suncat2000]

@GrantGryczan There's no implication that error 409 cannot be returned by a POST request. it can be used for version control, but is not required. From the spec: "Conflicts are most likely to occur in response to a PUT request" doesn't mean a POST is prohibited. Repeating your opinion in many of the other answers here doesn't make it any more correct. RFC7231 (published 4 years after the original question) makes it obvious that error 303 See Other is recommended for an existing resource, reporting where it is. For an append, as the OP stated, 200 or 204 would be more appropriate.

[Suncat2000]

This would be appropriate if the server were still processing the request. 200 or 204 would be more common. Since the OP is making an append request, existence of the object is an expected condition and not an error.

[Suncat2000]

POST is also used for appending data. This is by definition, not an error.

[Suncat2000]

The request is not duplicating a resource, it is appending data to one. In my opinion, yours is the best answer of all.

[Grant Gryczan]

Nothing is "prohibited". They're just specs. You don't have to follow them. But if you want to, I'd argue 422 is more appropriate. Also, 303 is a redirection code. You aren't redirecting to anything.

[lucastamoios]

There is no sense in saying to the client that the request was accepted because you already knows that it wasn't!

[JWAspin]

I would not infer that a 409 error cannot be returned by a POST, in fact, I would infer the opposite because "Conflicts are most likely to occur in response to a PUT request." seems to indicate that other request methods can also use this code. Additionally, "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." (webdav.org/specs/rfc2616.html#status.409)

[JWAspin]

@MavrickLaakso The ability to discover the existence of a resource in any system is not a problem if you have real security. What you're suggesting is "security through obscurity" which is generally recognized as not real security. Additionally, if a user is attempting to register an email address for a service, simply returning 400 is not useful, the user needs to know that email is taken so they can choose something else. Generically speaking, you can always authenticate a user prior to any attempts to create new resources.

[laaksom]

@JWAspin There isn't a right answer here, and there are tradeoffs to both. If I'm a malicious user, and the system respects status codes, a 409 lets me at least compile a list of valid emails to try to breach into. A 400 doesn't necessarily allow me to do the same. That was the point I was attempting to make.

[Timo Huovinen]

But what if the URL is the same but the method differs? For example you're not allowed to POST that here because you've posted it already, but you're allowed to PUT it here?

[gsaslis]

@Adrian and lucastamoios i think you are both assuming the server synchronously reads from the database, before providing the response. This is not always the case, so this answer is not "wrong", since the server doesn't always "know" about the existing record. This is very much the case in asynchronous systems where the api layer simply records the requests for processing by background workers.

[Grant Gryczan]

@Suncat2000 Even given that's the case, if the data is not successfully appended, there is still an error. And if the resource already exists, no data is going to be appended.

[Grant Gryczan]

Bad Request means that there is an inherent problem with the syntax of the packet. If, in another context (such as the resource not already existing), the packet would succeed, then it should not return error 400.

[osiixy]

422 just as an addition I agree with @GrantGryczan (stackoverflow.com/a/49709547/1124446) 422 Unprocessable Entity, which is used when a request is invalid but the issue is not in syntax or authentication

[Sebastian]

I also downvoted this. 4xx should be used instead. 3xx are supposed to be handled automatically from the client without user interaction. 4xx are client errors that users should take some action. In this case, change body payload, path variables, or do nothing.

[Nullius]

@Sebastian Could you provide a trustworthy source (e.g. IETF RFC) that a 3xx response coming from a REST service should be handled automatically by the client, without user interaction? I just referenced an RFC, exactly stating what I said in my original answer. If your point is valid, that RFC might need to be revised.

[Sebastian]

@Nullius, section 6.4 were states "The 3xx (Redirection) class of status code indicates that further action needs to be taken by the user agent in order to fulfill the request". The user agent refers generally not to the client of the API, instead potentially the client that handles HTTP requests. From a API client users perspective, you may choose what fit best. In most cases, you aren't instered in the existing resource but in your POST response wen't OK.

[Sebastian]

for instance, a redirection may be done as a side effect of your call from your HTTP client without you, client API even notice.

[Nullius]

Tbh, I still do not see a problem here. In section 6.4.4 about the 303 See Other status, right below the 3xx section you mentioned, it states "This status code is applicable to any HTTP method. It is primarily used to allow the output of a POST action to redirect the user agent to a selected resource, since doing so provides the information corresponding to the POST response". To me, it states even more clearly that a 303 is the right status as its result should correspond to a 'normal' POST response.

[Fernando Ferreira]

"The members of a DAV binding have already been enumerated in a previous reply to this request, and are not being included again."

[rwenz3l]

422 is webdav spec so I would not advise to use this for a REST API

[Chaim Klar]

Thanks, IMHO this IS the correct answer for THIS question, Thanks for point to the RFC, it again states the same. you forgot to mention, the RFC points out that 303 should be accompanied with the "Location" response header,which can also be used for caching. this is beautiful. 409 conflict is NOT the right response for many reasons; 1. 4xx usually means they user did something bad and more. 409 may be perfect, for when trying to add a record where biz rule allows only for one record of this type...

[selalerer]

403 is forbidden

[Manjunath Bhadrannavar]

you are right @selalerer, the client is forbidden to perform the operation (adding the same resource)

[Joe Mills]

Agreed, to sum up: 300 codes are to help the client find the correct resource, 400 codes indicate the request won't be processed due to it's construction or content. So we can do either: - 303 redirect to the already created resource - 409 conflict if there is a reason to indicate error for recreation attempts

[perustaja]

@laaksom What if the system uses emails as the login identifier? If your system lets them know that an email is taken then they can just figure out this way.

[mxcl]

This is not an authoritative source of error code definitions, it is their list of their definitions for codes for their API.

[Paul Draper]

All 4xx errors are the client's "fault." All 5xx errors are the server's "fault." (And submitting duplicate data is something the client has to fix, not the server.)

[Sławomir Lenart]

@Paul Draper: There is no place for 5xx when the resource already exists. The order of 4xx, 2xx, 3xx is not a coincidence here. It will be mostly 4xx, but others are fair enough in many cases, especially when a client has totally no idea how to deal with a duplicate or it doesn't matter at all.

[Wade]

Where did you quote your description from? link? -- Mozilla's description seems to fit nicely: "The HTTP 409 Conflict response status code indicates a request conflict with current state of the target resource. Conflicts are most likely to occur in response to a PUT request. For example, you may get a 409 response when uploading a file which is older than the one already on the server resulting in a version control conflict." - developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 -- Keywords: "most likely.. to a PUT", meaning can be a POST, and "for example" not only.

[Grant Gryczan]

@rwenz3l Why not? It is fairly conventional, clearly fits the purpose, and communicates what it is intended to.

[Ben Rauzi]

Hahaha, I love this!

[orimdominic]

Is 451 not for GET requests? As the spec says ...indicates that the user requested a resource that is not available due to legal reasons, such as a web page for which a legal action has been issued

[Grant Gryczan]

@JWAspin It's most likely implying PATCH, not POST. It makes sense that PATCH would be less likely to conflict since PUT requests have to include all information about the resource, while PATCH only has to state changes. On the other hand, POST, just like PUT, also has to include all information about the resource, so it wouldn't make sense if they were implying POST requests are less likely to conflict. In fact it doesn't even make sense for there to be a conflict in a POST request given the reasoning from my last comment.