[grandalf]

There will be cases where an HTTP status code matches perfectly with an application specific scenario, and in those cases using an HTTP status code is not confusing.

The confusion comes when the API developer tries to shoehorn all application specific errors into pre-existing HTTP status codes.

In most cases it is clearer to simply adopt a payload format that includes application specific error codes, so that the clarity of your API does not depend on its incidental similarity to pre-existing HTTP codes.

422 is a class of errors, not a catch-all for all similar scenarios one might encounter in building an API.

[vfaronov]

> In most cases it is clearer to simply adopt a payload format that includes application specific error codes

Absolutely. This is a common practice and there’s even a proposed standard for it (RFC 7807). But such a payload need not be sent with 200 (OK). It can refine the status code instead of overriding it.

[grandalf]

> It can refine the status code instead of overriding it.

True, this is sometimes possible when (coincidentally) one of the HTTP specs or extensions defines one of the codes in a way that feels similar enough.

The mistake is to assume that there is already a code for everything and that one does not need to define application specific error codes, which is what many API developers do.