What is the appropriate HTTP status code response for a common failed request (and not an error)?

Question

I am creating a RESTful API that will handle a number of user interactions, including placing orders using saved credit cards.

In the case of a successful order, I return 200 OK, and in the case when the order request is incorrect or invalid, I return 400 Bad Request. But what should I return if there is a problem during the actual processing of the order?

• POSTS client order to server for user resource. If the user does not exist, 404 Not Found is returned.
• Format and order information confirmed. If invalid, 400 Bad Request is returned.
• The order is being processed. If the order is completed successfully, 201 Created is returned for the order. If an unexpected error occurs, a 500 Server Error is returned.

The last step is the problem: what can I return if the order is not completed for any other reason? Possible scenarios may include:

• Product sold
• Maximum user order reached
• Credit card transaction failed (insufficient funds, etc.).

It does not look like it would be suitable for 400 or 500. If I could see it as 400, if there is no better code - the request was invalid according to business rules. It just doesn't seem accurate.

Edit: Also found this existing discussion of the same topic. All the answers there seem to indicate the use of status codes for this type of violation, with some discussion between using the 400, 409, or 422 extensions.

Answer 1

You must use 400 for business rules. Do not return 2xx if the order has not been accepted. HTTP application protocol, never forget about it. If you return 2xx, the customer may assume that the order has been accepted, regardless of the information you send in the body.

---

From the RESTful Web Services Cookbook :

One common mistake some web services make is to return a status code that reflects success (status codes 200 to 206 and 300 to 307), but include a message body that describes the error condition. This prevents the detection of errors in software that supports HTTP compatibility. For example, the cache will store it as a successful response and serve it to subsequent clients, even when clients can successfully request it.

I will leave this to you to choose between 4xx and 5xx, but you must use the error status code.

Answer 2

You must use 4xx for a client error if the client can modify the request to get around the error. Use 5xx for a server error that the client cannot work with.

A sold product will be a server error. The client cannot modify the request in any way to circumvent the error. You can switch to another product, but will it be a new request?

The maximum user order reached is also a server error. Nothing the client can do to fix this error.

A credit card transaction failure will be a customer error. The customer can resend the request using another payment method or credit card number to resolve the error.

Answer 3

Type of error:

4×× Client Error 

Error code:

 422 Unprocessable Entity 

The server understands the type of content of the request object (therefore, the status code of an unsupported media file 415 is not suitable), and the syntax of the request object is correct (and the 400 Bad Request status code is inappropriate), but could not process the contained instructions.

For example, this error condition may occur if the body of the XML request contains well-formed (i.e., syntactically correct) but semantically erroneous XML instructions.

https://httpstatuses.com/422

Answer 4

I know this question is old, but today I came to the same question. If my user runs out of credits, what status code should my REST API return?

I tend to 402 Payment Required :

According to Wikipedia :

Reserved for future use. The original intention was that this code could be used as part of some kind of digital cash or micropayment scheme, but this did not happen, and this code is usually not used. The Google Developers API uses this status if a particular developer has exceeded the daily request limit.

And really they do :

PAYMENT_REQUIRED (402)

• The daily budget limit set by the developer is reached.
• The requested operation requires more resources than the quota allows. Payment is required to complete the operation.
• The requested operation requires some payment from the authenticated user.

Answer 5

I don’t think 400 can be used for the whole business scenario. It can be used for basic data entry validation. In addition, it may be difficult for us to map other business logic to this error code. The error caused by this is mainly development-time errors that the developer will encounter, possibly during client coding.

Let's say all the parameters are correct and, for example, we pass the user account number into the request.

Thus, the request is no longer a bad request, the server can accept the request. But now he refuses to fill out a request on the basis of new available information, which - the account does not have sufficient balance.

I would suggest using 403 with the corresponding error message in these scenarios.

Another possible error code may be conflict 409. But this is used in scenarios in which the resource is in a state of consistency.

Answer 6

I am coming with 406 Not Acceptable .

Here is a list of 4xx:

 const HTTP_BAD_REQUEST = 400; const HTTP_UNAUTHORIZED = 401; const HTTP_PAYMENT_REQUIRED = 402; const HTTP_FORBIDDEN = 403; const HTTP_NOT_FOUND = 404; const HTTP_METHOD_NOT_ALLOWED = 405; const HTTP_NOT_ACCEPTABLE = 406; const HTTP_PROXY_AUTHENTICATION_REQUIRED = 407; const HTTP_REQUEST_TIMEOUT = 408; const HTTP_CONFLICT = 409; const HTTP_GONE = 410; const HTTP_LENGTH_REQUIRED = 411; const HTTP_PRECONDITION_FAILED = 412; const HTTP_REQUEST_ENTITY_TOO_LARGE = 413; const HTTP_REQUEST_URI_TOO_LONG = 414; const HTTP_UNSUPPORTED_MEDIA_TYPE = 415; const HTTP_REQUESTED_RANGE_NOT_SATISFIABLE = 416; const HTTP_EXPECTATION_FAILED = 417; const HTTP_I_AM_A_TEAPOT = 418; // RFC2324 const HTTP_MISDIRECTED_REQUEST = 421; // RFC7540 const HTTP_UNPROCESSABLE_ENTITY = 422; // RFC4918 const HTTP_LOCKED = 423; // RFC4918 const HTTP_FAILED_DEPENDENCY = 424; // RFC4918 const HTTP_RESERVED_FOR_WEBDAV_ADVANCED_COLLECTIONS_EXPIRED_PROPOSAL = 425; // RFC2817 const HTTP_UPGRADE_REQUIRED = 426; // RFC2817 const HTTP_PRECONDITION_REQUIRED = 428; // RFC6585 const HTTP_TOO_MANY_REQUESTS = 429; // RFC6585