api status code for post request that has failed

Question

I have an post api call that currently creates an appointment in my booking system.

If the api call sends the appointment request and the api can successfully create an appoinment the api returns a 201 created status code.

Currently if the appointment request is not created (due to various things such as the time is no longer available or the room is now being used) the api is returning a 400 bad request status code.

"400 Bad Request response status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error"

The data sent is not invalid syntax and potentially could be resent and be successful.

Is there a more relevant status code for this failure to create a resource. would 422 Unprocessable Entity be a valid response in this case?

Answer 1

409 could suit this use-case(and my personal preference):

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

Typically used in PUT but could work in this scenario. For example, they could change the proposed time in the request. Or they could retry later if the room becomes available.

422 could also work to indicate a field level error.

Either way, an important thing is to accompany it with a good error message indicating the issue. From rfc7231:

the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method.

Answer 2

[... ] if the appointment request is not created (due to various things such as the time is no longer available or the room is now being used) [...]

Status codes are meant to indicate the result of the server's attempt to understand and satisfy the client's request. Given that it's a client error, the most suitable status code would be in the 4xx range.

For the situation described in your question, you could use 409:

6.5.8. 409 Conflict

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 server SHOULD generate a payload that includes enough information for a user to recognize the source of the conflict. [...]

---

400 vs 422

In general, use 400 to indicate syntax errors in the payload or invalid parameters in the URL. And use 422 to indicate semantic problems in the payload. See how each status code is defined:

6.5.1. 400 Bad Request

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

11.2. 422 Unprocessable Entity

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. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.

Also consider the status codes returned by the well-known GitHub API v3 API:

There are three possible types of client errors on API calls that receive request bodies:

1. Sending invalid JSON will result in a 400 Bad Request response. [...]

2. Sending the wrong type of JSON values will result in a 400 Bad Request response. [...]

3. Sending invalid fields will result in a 422 Unprocessable Entity response. [...]

---

Michael Kropat put together a set of diagrams that's pretty insightful when it comes to picking the most suitable status code. See the following diagram for 4xx status codes: