Multiple error response types for a single http status code

[Chris Cleveland]

Swagger 2.0 defines error responses a little differently from 1.2. They look like this:

responses:
        200:
          // a good response
        400:
          // an error
        404:
          // a different error

What if my app has different kinds of errors that all map to error 400? Under this scheme, you get one and only one error response for a given code.

It's pretty standard behavior for rest apis to return different kinds of errors under the same code. For example, POST /person { firstname: Bob } could return "missing last name" or "bad zip code". There's no unique http status code that could distinguish the two.

In Swagger 1.2, error responses were returned in an array, which handled this problem nicely. In 2.0 the spec does not indicate that you can have an array of responses for a given http code.

How do I handle this situation?

[Ron]

Hi Chris,

I'm not sure that in 1.2 it was valid to have multiple responses for a given status code. I know the spec doesn't state it, but that may have been an oversight on my behalf.

However, it is not really necessary. Take your given example - while there can be several reasons for a given status code, documenting them separately gives you no added value.

In terms of display, you can definitely have a list of reasons per status code.
In terms of code-generation, you're going to end up dealing with a status code as a single case. The multiple 'reason string descriptions' have no logical effect on the matter.

Eventually, if you want the user of the API to tell the difference between the errors, you're likely to use some kind of response that will add that description, and the specific use cases should be described with that.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Max Lincoln]

I agree w/ Ron. I only support one response model per status code, though I'd like to see multiple examples per status code in the future.

I just thought I'd share a concerete example. Here's one based on IIS substatus codes:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"status_code": 401, "sub_code": 1, "message": "Access is denied due to invalid credentials."}

Versus:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"status_code": 401, "sub_code": 2, "message": "Access is denied due to server configuration favoring an alternate authentication method."}

I think that's a best practice for passing additional error details back to the client. It's important that the schema is always the same for the 401 status code (and ideally for all error status codes). You could document or give examples of the different possible sub_codes, but it's not good if the API returns a completely different JSON structure for some errors rather than always returning JSON with "sub_code" and "message" fields.