As far as I checked on many swagger files of Amazon/Google and more, That error code (or generally error codes of 5xx family) is not shown as a part of the swagger files. Is their a reason for that?
I am asking because one of our microservices API returns 500 when it fails to communicate to other service (for instance) and we are wondering if that error code should be part of our swagger files.
Should Internal error (500) be part of Swagger API documentation?
Viewed 1253
2 Answers
Generally clients/consumers can't do much upon getting the 5xx errors, since those are purely server side errors. So it need not to be part of your API specification.
If you think, based on the error which the API throws, client/consumer should do something (For example retry or try another site or so.), then Yes.
I think API documentation should only contain expected errors such as 4xx ones. But 5xx are unexpected errors and should not be documented.
Related