内部服务器错误是否应该以书面形式记录在案？

Question

我正在编写一个新的API并使用Swagger / OpenAPI对其进行记录。开发人员可以期望遇到的记录错误响应的好标准。 但是我找不到有关内部服务器错误的任何准则或最佳实践。理论上，每条路径都可能引发未处理的异常。我不希望它发生，但是可能会发生。应该是所有路径都有状态码为500“内部服务器错误”的响应，还是仅记录响应，开发人员可以做任何事情，例如2xx，3xx和4xx？

Answer 1

在responses部分中用于指定所有5xx状态代码的官方文档shows an example，但未涉及有关特定状态代码或返回消息的详细信息。它还提到API规范应该只包含已知错误：

  

请注意，API规范不一定需要涵盖所有可能的HTTP响应代码，因为它们可能事先未知。但是，它有望涵盖成功的响应和任何已知的错误。 “已知错误”是指，例如，对于返回按ID返回资源的操作的404 Not Found响应，或者在无效的操作参数的情况下为400 Bad Request响应。

您可以遵循相同的方法，并像示例中一样指定它。我认为这并不重要，甚至不建议尝试更具体地描述它，因为您可能仍然无法覆盖所有情况，并且不希望客户端对因内部服务器错误而返回的消息采取行动（可能不是以后重试） 。因此，例如，我不建议为其指定消息格式。

省略任何带有5xx HTTP错误代码的响应也是有道理的。