Should Internal error (500) be part of Swagger API documentation?

Question

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.

Pratt

Does this answer your question? Should Internal Server Error be documented in swagger? – Braided

Answer 1

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.

Hangbird

Ok, Thanks. If you say 5xx error is not an acceptable error generally, so what error code should my microservice return in case it coudn't communicate with another service (in case of network failure, for instance)? – Pratt

I didn't say 5XX errors are not acceptable generally.. in case of server side errors, API should respond with 5xx errors.. what i meant is, it should not be part of API specification share with consumers/clients. – Hangbird

Answer 2

I think API documentation should only contain expected errors such as 4xx ones. But 5xx are unexpected errors and should not be documented.

Homelike