Using client side error code 409 Conflict, instead of sending 500 Internal Server Error, 422 Unprocessable Entity or 400 Bad Request
When a new record is created 201 Created
is sent in the status code. When the response is 202 Accepted
, even in such a case sending another request can lead to error. Usually applications can throw 500 Internal Server Error
if any other error code is not configured or the error is not handled on the server.
During API testing, getting a 4XX code means the error is due to client activity. A generic 400 error will help the testing client validate the issue is at the client end. 500 error puts the blame on the server.
The reason for switching from the 400 status code to 409 is because the latter more accurately describes the reason for the API request failing. In the case of an issue transition request returning a 409, it means that an existing transition is still being executed, and that your app should employ a retry mechanism.
To prepare for this change, we recommend that your apps are capable of handling both the existing 400 error case, and the new 409 error case. After the change takes affect, you should make the appropriate functional changes in the 400 error case, moving any “Conflict” handling to the 409 error case.
Conflicts are most likely to occur in response to a PUT request. For example, you may get a 409 response when uploading a file that is older than the existing one on the server, resulting in a version control conflict.
The 422 Unprocessable Entity status code means the server understands the content type of the request entity, but the data is invalid. Still this doesn't tell say record is a duplicate.
Here it would be helpful to send back the details of the existing record, which was created with 201 Created
.
Here 303 See other
can also help, in case of distinguishing another conflicting resource. But it should not be used to throw the error, since it doesn't represent the duplicate record created by the client.