Должна ли Внутренняя ошибка (500) быть частью документации API Swagger?

Question

Насколько я проверял на многих файлах чванства Amazon / Google и других, этот код ошибки (или вообще коды ошибок семейства 5xx) не отображается как часть файлов чванства. Это их причина?
Я спрашиваю, потому что один из наших API микросервисов возвращает 500, когда он не может связаться с другим сервисом (например), и мы задаемся вопросом, должен ли этот код ошибки быть частью наших чванских файлов.

Answer 1

Я думаю, что документация API должна содержать только ожидаемые ошибки, такие как 4xx. Но 5xx являются неожиданными ошибками и не должны документироваться.

Answer 2

Как правило, клиенты / потребители не могут многое сделать при получении ошибок 5xx, поскольку это чисто ошибки на стороне сервера. Поэтому не должно быть частью вашей спецификации API.

Если вы считаете, что, основываясь на ошибке, которую выдает API, клиент / потребитель должен что-то сделать (например, повторить попытку или попробовать другой сайт или около того), тогда Да.