API 设计中的业务错误应该使用哪个 HTTP 状态码？

Question

假设我有一个 API 端点，它执行一些业务操作，这可能导致许多不直接连接到请求的不同故障。

请求格式正确，我无法返回 4xx 失败，但应用程序的逻辑要求我返回不同的错误消息。

现在我希望客户端能够区分这些错误消息，以便可以根据代码采取不同的操作。我可以像这样返回自定义 JSON，例如

{
  "code": 15,
  "message": "Some business error has occurred"
}

现在的问题是，如果没有像 Conflict 或 NotFound 这样的标准代码有意义，我应该在这种情况下使用哪种 HTTP 状态代码。

似乎 500 InternalServerError 是合乎逻辑的，但是我怎么能另外标记这不能重试，如果它只是记录给定的状态代码是不可能重试的，所以如果你没有得到可以重试其中之一？

Answer 1

咨询RFC 7231:

503 Service Unavailable 看起来像一个潜在的候选者，但 RFC 提到这应该代表一个“可能会在延迟一段时间后得到缓解”的问题。这将向客户表明它可以稍后尝试相同的呼叫，可能是在工作时间之后或周末。这不是你想要的。

501 Not Implemented 是可能的，但 RFC 提到“这 是服务器无法识别时的适当响应 request 方法，并且不能支持任何资源。默认情况下，501 响应是可缓存的；”这里似乎不是这种情况 - HTTP 方法本身可能是有效的 - 这里的失败似乎发生在 业务规则 层（例如，发送一个不在数据库中的帐号），而不是一个你从来没有实现过的 HTTP 方法（GET、POST 等）。

剩下最后一个认真的候选人，

500 内部服务器错误

500（内部服务器错误）状态码表示服务器 遇到了阻止它实现的意外情况 请求。

这是通常用于一般“应用程序中发生异常”情况的错误代码。 500是最好的选择。

关于如何将此与“暂时性内部故障”错误区分开来，您可以将其作为HTTP body 的一部分包含在内 - 只需确保您的客户可以解析出自定义代码！