What's the best return code for "@unique" violations?

Question

I'm working on a RESTful web API with a Hibernate powered back-end. So far, we've mapped a few error codes. For instance, when @Version validation fails, our API returns HTTP error code 409.

Now, we need to map the best error code to be returned when unique validation fails. For instance, my API has a business rule which says that there cannot be two instances of entity A with the same name. For instance, if I have a record in my DB with name = "XYZ", I cannot create another record in the database with the same name "XYZ". What would be the best return code in this case? 409 as well?

I've done some research in both "REST in Practice" book and Google, and 409 seems to be mostly associated with @Version, I couldn't any references to 409 being used with unique validations.

Any help is greatly appreciated! Thanks!

Answer 1

I would first consider 422 Unprocessable Entity:

The 422 (Unprocessable Entity) status code means the server
understands the content type of the request entity, and the
syntax of the request entity is correct but was unable to process the contained instructions.

In this case, the contained instructions are "please create this new resource".

409 Conflict is also often used, the argument being that the existence of the resource is in conflict with the attempt to create a new one:

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. This code is used in situations where the user might be able to resolve the conflict and resubmit the request.

The rest of the explanation for this response code is about resolving the conflict, which isn't possible in your case. That's why I lean away from this response code.

A third option would be 403 Forbidden:

The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it. [..] However, a request might be forbidden for reasons unrelated to the credentials.

Most people get scared off of this code by the auth implications, but the text clearly states that it's appropriate in other situations.

Without much more information about your system, nobody's going to be able to tell you the exact correct code to use. Take a look at the definitions of those responses and pick the one that best meets your needs. Whichever response code you select, make sure the response entity clearly outlines the problem so the client can correct it.