Dilemma between 2xx and 4xx status codes in api rest

Question

I think this problem is not trivial, so I would like to express it in detail

Domain:

I have an endpoint (api rest) that receives a date and time of an appointment that I want to block (which will later be reserved). The operation is simple, when receiving the date and time, it is blocked so that another client can not book an appointment on the same day and time, while the one that blocks the appointment, completes the contact information.

So far, very simple. The problem begins when two different users select the same date and time in their browser and two requests are triggered simultaneously. As we already know, you can not block an appointment on the same day and time twice, so the application will fail (although this failure is properly controlled).

In short, two users try to block an appointment on the same date and time, and only the request that is processed first will succeed. For the user who managed to block the appointment, the answer is clear: 200 OK status. The question is, which state code http corresponds to return to the second user?

Comment:

Very recently at work I have run into this dilemma, and I have argued strongly with a co-worker about it. Since then, I began to research hard and consult with several people with years of experience in the subject to be able to reach a conclusion.

• 2xx: Half of the people answered that the state code should be a 2xx. Why? first of all, because the request is well formulated (mainly the parameters, are written correctly) so it would not correspond to a client error (4xx) and on the other hand, it is not an unexpected error of the server (500), since it is duly controlled by the business logic itself. Since the query was done properly, it should send a 2xx status (more precisely a 200) indicating that the request was successful, with a message on the body, indicating the "status" of the action (the appointment could not be blocked) .
• 4xx: My position (and also that of the other 50% of those consulted) is that, as can be seen, the request fails because the desired action can not be completed. It does not seem logical at all, that a 200 OK is returned (indicating that everything went well) and a message describing the error or condition that occurred (in a way, it would be contradicting me). As an error occurred, there are only 2 possible guilty: the client and the server. In this case, it seems to me that the server is not, because it does not fail unexpectedly, but that business rule is well contemplated, and intentionally fails (so it would not be a 5xx). Everything seems to fit in that it is a client error, perhaps a semantic error, when trying to perform the same operation twice on the same resource. Therefore, my opinion is that an error 400 would adjust to the situation, and perhaps if we want to be a little more specific, a 409, indicating that we tried to modify concurrently a resource that does not allow this action.

What should be the appropriate option for this case?

Thanks!

Answer 1

Let us look at what the Wikipedia and MDN has to offer on this:

2xx (Successful): The request was successfully received, understood, and accepted

4xx (Client Error): The request contains bad syntax or cannot be fulfilled

(source: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)

In the case of an appointment conflict, the request of the second user is received and understood but can not be accepted so it would seem to be wrong to return a 2xx for such a case.

A situation qualifies for a 4xx either when the request contains a bad syntax (which is not the case here as the request is well-formed) or when the request cannot be fulfilled (which seems to be the case here which you want to communicate back to the client). A suggestion can be to go ahead with 422 for such kind of errors which are specific to a business use case (such as an appointment scheduler for your case)

As per MDN:

The HyperText Transfer Protocol (HTTP) 422 Unprocessable Entity response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.

(source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422)

Also since booking an appointment would create a resource in the back-end (i.e. a valid appointment id with the details of visitor, time, etc.), I would prefer to send back 201 (Created) status code for the success case as you are executing the task in a synchronous manner. In my opinion, 200 (OK) status code is more suitable for situations when the resource would be asynchronously created and may not immediately be available when the server responses back to the client. In such cases we generally provide a GET request link from where the client can fetch the requested resource in future.