Definitions for error responses #398
Description
It's obvious that each api will have a bunch of errors. Each request can usually raise one of several errors (where subsets can differ for different routes).
Current scheme allows only one response with given status code. While this is generally okay for successful responses (like 200 OK, 301 Redirect etc) it doesn't play well with codes above 400. For example, 400 Bad Request can be caused by many reasons, such as missing fields, extra fields, incorrect data or other preconditions. It is required to let client know what errors can he expect for each request and what playload (if any) will each error have.
This all leads to a requirement of having errors (or exceptions) definition.
It can be similar to current responses section, and each request method would have list of errors (exceptions?) that might be raised.
Another useful thing is to have api-wide exceptions. The best examples of such are 401 Unauthorized and 500 Server Error as they can be raised almost by any request.