Document errors that could occur within 4xx/5xx #567

Open
jharmn opened this Issue Feb 16, 2016 · 7 comments

Projects

None yet

7 participants

@jharmn
Member
jharmn commented Feb 16, 2016

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'.

@Shulamite

We extend this:
http://datatracker.ietf.org/doc/draft-ietf-appsawg-http-problem/
and add a few additional fields.

@webron webron added the Sub Issue label Feb 22, 2016
@webron
Member
webron commented Feb 22, 2016

Parent: #566 (pretty sure you wanted to do that, @jasonh-n-austin ;)).

@jharmn
Member
jharmn commented Feb 25, 2016

@Shulamite in order to support different APIs, we'd have to keep the definition of the error object loosely coupled (i.e. just a reference to an error field which provides a unique index of the potential errors). Prescribing a specific API error standard would preclude any existing API that doesn't use http-problem from using OAS.

@haack
haack commented Mar 18, 2016

Agreed, being able to define error codes at a top level in swagger.yaml would be extremely useful. Possibly in the definitions?

@balsagoth

One more here

@arno-di-loreto

It's useful but isn't it too much specific? I mean every API handles errors differently (even if there's the RFC7807).
BTW: I ended add an x- structure to my company OpenAPI spec to describe errors beyond HTTP status

@tadhgpearson

I don't really understand what the issue is, is it just to define the HTTP status message?

You define an error as a model object through
paths/{url}/{verb}/response/{status_code},

like this

responses:
        200:
          description: Valid Response
          schema:
            $ref: "#/definitions/Response"
        400:
           description: Client input error
            schema:
              $ref: "#/definitions/ClientError"
        default:
          description: Client or server error
          schema:
            $ref: "#/definitions/Error"    

and then in your definitions

Error:
    required:
      - status
      - code
      - message
    properties:
      status:
        type: integer
      code:
         type: string
         enum: [MISSING_REQUIRED_PARAMETER, INVALID_INPUT, OTHER]
      message:
        type: string
      more_info:
        type: string

Is this also to define a generic error set for all APIs, rather than having to do this at an individual request level?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment