HTTP response code for POST when resource already exists

C

Community

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.

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).

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.

@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.

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

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

C

Community

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.

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.

This is the most RESTful answer.

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.

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.

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.

S

Sławomir Lenart

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.

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

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.)

@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.

C

Community

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.

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.

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

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.

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.

@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.

p

p0lar_bear

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.

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.

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.

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.

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 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.

G

Grant Gryczan

I would go with 422 Unprocessable Entity, which is used when a request is invalid but the issue is not in syntax or authentication.

As an argument against other answers, to use any non-4xx error code would imply it's not a client error, and it obviously is. To use a non-4xx error code to represent a client error just makes no sense at all.

It seems that 409 Conflict is the most common answer here, but, according to the spec, that implies that the resource already exists and the new data you are applying to it is incompatible with its current state. If you are sending a POST request, with, for example, a username that is already taken, it's not actually conflicting with the target resource, as the target resource (the resource you're trying to create) has not yet been posted. 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." The request to create another user with that username is just unprocessable, having nothing to do with any version conflict.

For the record, 422 is also the status code GitHub uses when you try to create a repository by a name already in use.

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

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

w

wombatonfire

After having read this and several other, years-long, discussions on status code usage, the main conclusion I came to is that the specifications have to be read carefully, focusing on the terms being used, their definition, relationship, and the surrounding context.

What often happens instead, as can be seen from different answers, is that parts of the specifications are ripped of their context and interpreted in isolation, based on feelings and assumptions.

This is going to be a pretty long answer, the short summary of which is that HTTP 409 is the most appropriate status code to report the failure of an "add new resource" operation, in case a resource with the same identifier already exists. What follows is the explanation why, based solely on what's stated in the authoritative source - RFC 7231.

So why is 409 Conflict the most appropriate status code in a situation described in the OP's question?

RFC 7231 describes 409 Conflict status code as follows:

The 409 (Conflict) status code indicates that the request could not be completed due to a conflict with the current state of the target resource.

The key components here are the target resource and its state.

Target resource

The resource is defined by the RFC 7231 as follows:

The target of an HTTP request is called a "resource". HTTP does not limit the nature of a resource; it merely defines an interface that might be used to interact with resources. Each resource is identified by a Uniform Resource Identifier (URI), as described in Section 2.7 of [RFC7230].

So, when using a HTTP interface, we always operate on the resources identified by URIs, by applying HTTP methods to them.

When our intention is to add a new resource, based on the OP's examples, we can:

use PUT with the resource /objects/{id};

use POST with the resource /objects.

/objects/{id} is out of interest, because there can be no conflict when using a PUT method:

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload.

If the resource with the same identifier already exists, it will be replaced by PUT.

So we'll focus on the /objects resource and POST.

RFC 7231 says about the POST:

The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics. For example, POST is used for the following functions (among others): ... 3) Creating a new resource that has yet to be identified by the origin server; and 4) Appending data to a resource's existing representation(s).

Contrary to how the OP understands POST method:

Since POST is meant as "append" operation...

Appending data to a resource's existing representation is just one of the possible POST "functions". Moreover, what the OP actually does in the provided examples, is not directly appending data to the /objects representation, but creating a new independent resource /objects/{id}, which then becomes part of the /objects representation. But that's not important.

What's important is the notion of the resource representation, and it brings us to...

Resource state

RFC 7231 explains:

Considering that a resource could be anything, and that the uniform interface provided by HTTP is similar to a window through which one can observe and act upon such a thing only through the communication of messages to some independent actor on the other side, an abstraction is needed to represent ("take the place of") the current or desired state of that thing in our communications. That abstraction is called a representation [REST].

For the purposes of HTTP, a "representation" is information that is intended to reflect a past, current, or desired state of a given resource, in a format that can be readily communicated via the protocol, and that consists of a set of representation metadata and a potentially unbounded stream of representation data.

That's not all, the specification continues to describe representation parts - metadata and data, but we can summarize that a resource representation, that consists of metadata (headers) and data (payload), reflects the state of the resource.

Now we have both parts needed to understand the usage of the 409 Conflict status code.

409 Conflict

Let's reiterate:

The 409 (Conflict) status code indicates that the request could not be completed due to a conflict with the current state of the target resource.

So how does it fit?

We POST to /objects => our target resource is /objects. OP does not describe the /objects resource, but the example looks like a common scenario where /objects is a resource collection, containing all individual "object" resources. That is, the state of the /objects resource includes the knowledge about all existing /object/{id} resources. When the /objects resource processes a POST request it has to a) create a new /object/{id} resource from the data passed in the request payload; b) modify its own state by adding the data about the newly created resource. When a resource to be created has a duplicate identifier, that is a resource with the same /object/{id} URI already exists, the /objects resource will fail to process the POST request, because its state already includes the duplicate /object/{id} URI in it.

This is exactly the conflict with the current state of the target resource, mentioned in the 409 Conflict status code description.

A

Abd Abughazaleh

In your case you can use 409 Conflict

And if you want to check another HTTPs status codes from below list

1×× Informational

100 Continue
101 Switching Protocols
102 Processing

2×× Success

200 OK
201 Created
202 Accepted
203 Non-authoritative Information
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status
208 Already Reported
226 IM Used

3×× Redirection

300 Multiple Choices
301 Moved Permanently
302 Found
303 See Other
304 Not Modified
305 Use Proxy
307 Temporary Redirect
308 Permanent Redirect

4×× Client Error

400 Bad Request
401 Unauthorized
402 Payment Required
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
407 Proxy Authentication Required
408 Request Timeout
409 Conflict
410 Gone
411 Length Required
412 Precondition Failed
413 Payload Too Large
414 Request-URI Too Long
415 Unsupported Media Type
416 Requested Range Not Satisfiable
417 Expectation Failed
418 I’m a teapot
421 Misdirected Request
422 Unprocessable Entity
423 Locked
424 Failed Dependency
426 Upgrade Required
428 Precondition Required
429 Too Many Requests
431 Request Header Fields Too Large
444 Connection Closed Without Response
451 Unavailable For Legal Reasons
499 Client Closed Request

5×× Server Error

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates
507 Insufficient Storage
508 Loop Detected
510 Not Extended
511 Network Authentication Required
599 Network Connect Timeout Error

A

Alfonso Tienda

I don't think you should do this.

The POST is, as you know, to modify the collection and it's used to CREATE a new item. So, if you send the id (I think it's not a good idea), you should modify the collection, i.e., modify the item, but it's confusing.

Use it to add an item, without id. It's the best practice.

If you want to capture an UNIQUE constraint (not the id) you can response 409, as you can do in PUT requests. But not the ID.

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?

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.

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.

@partkyle Stop using PKs as public IDs!!

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

a

alanjds

"302 Found" sounds logical for me. And the RFC 2616 says that it CAN be answered for other requests than GET and HEAD (and this surely includes POST)

But it still keeps the visitor going to this URL to get this "Found" resource, by the RFC. To make it to go directly to the real "Found" URL one should be using "303 See Other", which makes sense, but forces another call to GET its following URL. On the good side, this GET is cacheable.

I think that I would use "303 See Other". I dont know if I can respond with the "thing" found in the body, but I would like to do so to save one roundtrip to the server.

UPDATE: After re-reading the RFC, I still think that an inexistent "4XX+303 Found" code should be the correct. However, the "409 Conflict" is the best existing answer code (as pointed by @Wrikken), maybe including a Location header pointing to the existing resource.

3xx statuses are meant for redirection

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

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".

@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.

@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.

S

Sinaesthetic

I think for REST, you just have to make a decision on the behavior for that particular system in which case, I think the "right" answer would be one of a couple answers given here. If you want the request to stop and behave as if the client made a mistake that it needs to fix before continuing, then use 409. If the conflict really isn't that important and want to keep the request going, then respond by redirecting the client to the entity that was found. I think proper REST APIs should be redirecting (or at least providing the location header) to the GET endpoint for that resource following a POST anyway, so this behavior would give a consistent experience.

EDIT: It's also worth noting that you should consider a PUT since you're providing the ID. Then the behavior is simple: "I don't care what's there right now, put this thing there." Meaning, if nothing is there, it'll be created; if something is there it'll be replaced. I think a POST is more appropriate when the server manages that ID. Separating the two concepts basically tells you how to deal with it (i.e. PUT is idempotent so it should always work so long as the payload validates, POST always creates, so if there is a collision of IDs, then a 409 would describe that conflict).

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.

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

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."

I do like your suggestion to use PUT though.

C

Community

Another potential treatment is using PATCH after all. A PATCH is defined as something that changes the internal state and is not restricted to appending.

PATCH would solve the problem by allowing you to update already existing items. See: RFC 5789: PATCH

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.

F

Fernando Ferreira

What about 208 - http://httpstatusdogs.com/208-already-reported ? Is that a option?

In my opinion, if the only thing is a repeat resource no error should be raised. After all, there is no error neither on the client or server sides.

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.

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

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

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

@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.

C

Community

Stumbled upon this question while checking for correct code for duplicate record.

Pardon my ignorance but I don't understand why everyone is ignoring the code "300" which clearly says "multiple choice" or "Ambiguous"

In my opinion this would be the perfect code for building a non standard or a particular system for your own use. I could be wrong as well!

https://www.rfc-editor.org/rfc/rfc7231#section-6.4.1

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.

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"..

C

Community

More likely it is 400 Bad Request

[**6.5.1. 400 Bad Request**][1]

The 400 (Bad Request) status code indicates that 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).

As the request contains duplicate value(value that already exists), it can be perceived as a client error. Need to change the request before the next try. By considering these facts we can conclude as HTTP STATUS 400 Bad Request.

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.

佚

佚名

Error 402, payment required

I.E. this resource already exists but if you give me enough money I'll delete the current one and give it to you :D

...but looking at mozilla's definition of status codes at https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses

as a more serious answer that no one has provided here, what about 451: unavailable for legal reasons. You cannot "legally(by terms and conditions put in place by yourself)" give multiple people access to the same account information

422 is also a good option which is Unprocessable Entity The request was well-formed but was unable to be followed due to semantic errors. since it is a perfectly valid request but due to it being semantically equal to another entry, it cannot be followed.

Hahaha, I love this!

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

k

kishor borate

Since you mentioned that the object create request using post contains the ID of the object, you should make it an idempotent request. Just return the exact same response as a successful create request. Idempotent request makes APIs simpler, eg. now client doesn't have to worry about 2 different cases (success, failure). or client can safely retry the request, in case something goes wrong in connectivity/ server temporarily down.

M

Manjunath Bhadrannavar

This is a user side fault and belongs to 4xx group. This is the right answer https://developers.rebrandly.com/docs/403-already-exists-errors

403 is forbidden

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

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

Why Rebrandly chose to alter the HTTP response code spec instead of just adding new codes at the end is strange. @ManjunathBhadrannavar may have already learned in the past two years, but 401 Unauthorized means the user isn't authenticated (Missing or bad credentials) and 403 Forbidden means not authorized (Good credentials, but lacks permission for that endpoint). 403 is not the right choice here because it has nothing to do with the client lacking permissions.

HTTP response code for POST when resource already exists

Follow WeChat

Want to stay one step ahead of the latest teleworks?

相似问题

Platform

Support

Links

Contact US