What is the appropriate HTTP status code response for a general unsuccessful request (not an error)?

Question

You should use 400 for business rules. Don't return 2xx if the order was not accepted. HTTP is an application protocol, never forget that. If you return 2xx the client can assume the order was accepted, regardless of any information you send in the body.

---

From RESTful Web Services Cookbook:

One common mistake that some web services make is to return a status code that reflects success (status codes from 200 to 206 and from 300 to 307) but include a message body that describes an error condition. Doing this prevents HTTP-aware software from detecting errors. For example, a cache will store it as successful response and serve it to subsequent clients even when clients may be able to make a successful request.

I'll leave it to you to decide between 4xx and 5xx, but you should use an error status code.

You should use 4xx for a client error if the client can modify the request to get around the error. Use a 5xx for a server error that the client can't really work around.

Product sold out would be a server error. The client can't modify the request in some fashion to get around the error. You could switch to another product but wouldn't that be a new request?

User maximum order limit reached is also a server error. Nothing the client can do to work around that error.

Credit card transaction failure would be a client error. The client could resubmit the request with a different payment method or credit card number to work around the error.

Error type:

4×× Client Error

Error code:

422 Unprocessable Entity

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.

https://httpstatuses.com/422

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

I tend to lean towards 402 Payment Required:

According to Wikipedia:

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

And indeed they do:

PAYMENT_REQUIRED (402)

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