400 vs 422 for Client Error Request

Question

I've read a lot of posts and articles regarding proper http status code to return for client request error. Others suggest to use 400 as it has been redefined in RFC 7231 though I'm not sure if the example given covers all the client error in my mind because the examples are syntactic.

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

I did find this statement in the Appendix B of the rfc 7231:

The 400 (Bad Request) status code has been relaxed so that it isn't
limited to syntax errors. (Section 6.5.1)

Does this mean that I can consider any type of client error a bad request? Would it be better to use 400 for client requests and just specify a more specific error in the message?

On the other hand, others say that it's better to use 422 (Unprocessable Entity). While this is more focused on semantics, it's only listed in [RFC 4918][2] which is a webDAV extension for http/1.1

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.

Can I use this webDAV extension codes to handle my http requests? In the case of 422, can I use it even though it's not in the core http codes.

Should I use 400 or 422 for my client error?

Here are the possible client error I have in mind:

1.) Invalid parameter. The client provided parameters but are found invalid. Example: I said that the userId is 1, but when I checked there's no userId of 1. Another example of invalid parameter is wrong data type.
2.) Missing required parameters
3.) Let's say I need to hash a value based on given params and it failed 
4.) Blocked content is being used. Like, i want to apply for membership and i passed the userId of 1. However, userId of one is blocked / deactivated
5.) When I try to delete an entry but the entry is still being used in another table. 
6.) Let's say i require a signature in my payload and the signature does not match when recalculated in the backend
7.) Let's say I have a value that counts a specific attribute like "shares" and it has reached the maximum value like 10.
etc...

Any informative response will be highly appreciated. Thanks a lot, guys!

Update: I checked google api errors and they are not using 422. On the other hand, Twitter uses 422. I'm more confused than ever >.< Though there's a part of me that thinks 400 is the better choice as it is included in the RFC doc and 422 is not. I could be wrong though.

Answer 1

Can I use this WebDAV extension codes to handle my HTTP requests? In the case of 422, can I use it even though it's not in the core HTTP codes.

HTTP is an extensible protocol and 422 is registered in IANA, which makes it a standard status code. So nothing stops you from using 422 in your application.

And since June 2022, 422 is defined in the RFC 9110, which is the document that currently defines the semantics of the HTTP protocol:

Status code 422 (previously defined in Section 11.2 of RFC 4918) has been added because of its general applicability.

For reference, here's how 422 is defined:

15.5.21. 422 Unprocessable Content

The 422 (Unprocessable Content) status code indicates that the server understands the content type of the request content (hence a 415 (Unsupported Media Type) status code is inappropriate), and the syntax of the request content is correct, but it was unable to process the contained instructions. For example, this status code can be sent if an XML request content contains well-formed (i.e., syntactically correct), but semantically erroneous XML instructions.

While defined in the RFC 4918, the reason phrase of 422 was "Unprocessable Entity". Since it was added to the RFC 9110, it's reason phrase is "Unprocessable Content".

Should I use 400 or 422 for my client error?

You certainly could use both. 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.

As an example, see the approach used by the GitHub v3 API:

Client errors

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.

    HTTP/1.1 400 Bad Request
    Content-Length: 35
   
    {"message":"Problems parsing JSON"}
   

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

    HTTP/1.1 400 Bad Request
    Content-Length: 40
   
    {"message":"Body should be a JSON object"}
   

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

    HTTP/1.1 422 Unprocessable Entity
    Content-Length: 149
   
    {
      "message": "Validation Failed",
      "errors": [
        {
          "resource": "Issue",
          "field": "title",
          "code": "missing_field"
        }
      ]
    }
   

---

Picking the most suitable 4xx status code

Michael Kropat put together a set of decision charts that helps determine the best status code for each situation. See the following for 4xx status codes:

Problem details for HTTP APIs

HTTP status codes are sometimes not sufficient to convey enough information about an error to be helpful. The RFC 7807 defines simple JSON and XML document formats to inform the client about a problem in a HTTP API. It's a great start point for reporting errors in your API.

It also defines the application/problem+json and application/problem+xml media types.