Document errors that could occur within 4xx/5xx

In providing quality documentation, it’s necessary to provide more than “400 - Bad Request”. Usually, an error object defines a key which indicates more specifically what was wrong (this applies to 5xx range as well), usually referred to as an ‘error code’ (not the HTTP status code). In addition, when testing for whether a given error is intended to be produced by a given operation, it’s helpful to have the verb/uri/status correlated to a given ‘error code’. At a minimum, all potential ‘error codes’ should be documented for a given API (realm of verbs+uri’s+statuses). These ‘error codes’ could be numeric (e.g. 100100) or strings (e.g. AUTHORIZATION_VOIDED). The field/key they are mapped to could be variable, such as code, name.

Examples: https://developer.paypal.com/docs/api/#errors https://stripe.com/docs/api#errors

We store proprietary data to keep track of these correlations, at an API level (representing a group of verb/url/statuses):

"x-errors" : [
    {
      "name": "MALFORMED_REQUEST_ERROR",
      "message": "Json request malformed.",
      "information_link": "http://developer.paypal.com/apidoc/invoicing#MALFORMED_REQUEST_ERROR",
      "details" : "The Json request is malformed. Please check the request and resend the request."
    },
    // Long-list ensues

It would be very helpful to have the ability to specify what the ‘error code’ field is in error responses, and to provide a list of these errors. Defining them at a swagger.yaml level is a minimum, and at an operation/status level would be the most granular (probably useful in testing precision).

Perhaps in the spirit of #398, defining a global list of status codes would be useful, in addition to specific ‘error codes’.

[andy-maier]

@tadhgpearson: Your example shows the current shortcoming: There is only one piece of information for each HTTP status code. Many HTTP status codes above 400 can have multiple reasons, each. These reasons cannot be properly documented today. What is needed is:

• The ability to define multiple reason codes including a message, for each HTTP status code.
• The ability to define these reason codes globally, and the ability to reference these global definitions in the definition of an HTTP operation. Basically, each HTTP operation would reference a list of tuples (HTTP status code, reason code).

I definitely second the original request.

[sedapsfognik]

Would love to see this one in the next releases.