REST API错误返回良好做法[关闭]

我正在寻找有关从REST API返回错误的良好实践指南。我正在开发一个新的API，所以我现在可以朝任何方向发展。目前，我的内容类型是XML，但我计划将来支持JSON。

我现在添加了一些错误情况，例如，某个客户端尝试添加新资源，但已超出其存储配额。我已经在使用HTTP状态代码处理某些错误情况（身份验证为401，身份验证为403，普通错误请求URI为404）。我查看了受祝福的HTTP错误代码，但400-417范围似乎都不适合报告应用程序特定的错误。因此，起初我很想以200 OK和特定的XML有效负载返回我的应用程序错误（即，向我们支付更多，您将获得所需的存储空间！），但我停下来考虑一下，而且似乎很肥皂水（/耸了耸肩）。除此之外，感觉像是将错误响应分为不同的情况，因为有些是http状态代码驱动的，而另一些则是内容驱动的。

那么行业的建议是什么？良好做法（请解释原因！），以及从客户端pov看，REST API中的哪种错误处理使客户端代码的工作变得更轻松？

因此，起初我很想以200 OK和特定的XML有效负载返回我的应用程序错误（即，向我们支付更多，您将获得所需的存储空间！），但我停下来考虑一下，而且似乎很肥皂水（/耸了耸肩）。

除非请求确实没有错，否则我不会返回200。从RFC2616开始，200表示“请求已成功”。

如果超过了客户端的存储配额（无论出于何种原因），我将返回403（禁止访问）：

服务器理解了该请求，但拒绝执行该请求。授权将无济于事，不应重复该请求。如果请求方法不是HEAD，并且服务器希望公开为什么未满足请求，则应在实体中描述拒绝的原因。如果服务器不希望将此信息提供给客户端，则可以改用状态代码404（未找到）。

这告诉客户端该请求是可以的，但是失败了（200不能执行此操作）。这也使您有机会在响应正文中解释问题（及其解决方案）。

您还要考虑其他哪些特定的错误条件？

为您的API选择正确的HTTP错误代码的绝佳资源：http : //www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

文章摘录：

从哪儿开始：

2XX / 3XX：

4XX：

5XX：

主要选择是您是否要将HTTP状态代码视为REST API的一部分。

两种方式都可以正常工作。我同意，严格来说，REST的想法之一是您应该将HTTP状态代码用作API的一部分（成功操作返回200或201，并根据各种错误情况返回4xx或5xx。）但是，没有REST警察。你可以做你想做的。我已经看到了更令人震惊的非REST API被称为“ RESTful”。

此时（2015年8月），我建议您将HTTP状态代码用作API的一部分。现在，使用框架时比过去更容易看到返回代码。特别是，与过去相比，现在更容易看到非200的返回案例和非200的响应正文。

HTTP状态代码是您的api的一部分

1. 您将需要仔细选择适合您的错误条件的4xx代码。您可以包括rest，xml或纯文本消息作为有效负载，其中包括子代码和描述性注释。

2. 客户端将需要使用使他们能够获得HTTP级状态代码的软件框架。通常可行，但并不总是直截了当。

3. 客户端必须区分表示通信错误的HTTP状态代码和表示应用程序级问题的您自己的状态代码。

HTTP状态代码不属于您的api

1. 如果您的应用收到请求然后响应，则HTTP状态代码将始终为200（成功和错误情况）

2. 您的所有回复都应包含“信封”或“标题”信息。通常是这样的：

   信封版本：1.0
   状态：＃使用您喜欢的任何代码。保留成功代码。
   msg：“ ok”＃反映代码的人为字符串。对调试有用。
   数据：...＃响应的数据（如果有）。

3. 对于客户端，此方法可能更容易，因为响应的状态始终在同一位置（不需要子代码），没有代码限制，也不需要获取HTTP级别的状态代码。

这是具有类似想法的帖子：http: //yuiblog.com/blog/2008/10/15/datatable-260-part-one/

主要问题：

1. 确保包含版本号，以便以后可以根据需要更改api的语义。

2. 文献...

请记住，状态代码比HTTP / 1.1 RFC中定义的状态代码更多，IANA注册中心位于http://www.iana.org/assignments/http-status-codes。对于您提到的情况，状态码507听起来不错。

正如其他人指出的那样，在错误代码中包含响应实体是完全允许的。

请记住，5xx错误是服务器端的错误，也就是客户端无法更改其请求以使请求通过。如果超出了客户端的配额，那么这绝对不是服务器错误，因此应避免使用5xx。

有两种错误。应用程序错误和HTTP错误。HTTP错误只是让您的AJAX处理程序知道一切正常，不应将其用于其他任何事情。

5xx 服务器错误

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

2xx成功

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

但是，如何设计应用程序错误实际上取决于您。堆栈溢出例如发送出与对象response，data和message属性。我认为响应包含true或false指示该操作是否成功（通常用于写操作）。数据包含有效负载（通常用于读取操作），并且消息包含任何其他元数据或有用的消息（例如，response是时的错误消息false）。

我知道这对于聚会来说非常晚了，但是现在，在2013年，我们有几种媒体类型可以以常见的分布式（RESTful）方式处理错误处理。请参阅application / vnd.error + json（https://github.com/blongden/vnd.error）中的“ vnd.error”和application / problem + json（https://tools.com）中的“ HTTP API问题详细信息” 。 ietf.org/html/draft-nottingham-http-problem-05）。

同意 REST的基本原理是使用Web基础结构。HTTP状态代码是一种消息传递框架，它允许各方在不增加HTTP有效负载的情况下彼此通信。它们已经建立了传达响应状态的通用代码，因此，要真正实现RESTful，应用程序必须使用此框架来传达响应状态。

在HTTP 200信封中发送错误响应会产生误导，并迫使客户端（api使用者）最有可能以非标准或专有方式来解析消息。这也不是很有效-您将迫使客户端每次都解析HTTP有效负载以了解“真实”响应状态。这增加了处理，增加了延迟，并为客户端提供了一个出错的环境。

可以根据现有的“最佳实践”对api进行建模。例如，以下是Twitter处理错误代码 https://developer.twitter.com/en/docs/basics/response-codes的方式

请坚持协议的语义。将2xx用于成功响应，将4xx和5xx用于错误响应-无论是业务异常还是其他情况。如果将2xx用于任何响应是协议中的预期用例，则它们最初将没有其他状态代码。

不要忘记5xx错误以及应用程序错误。

在这种情况下，409（冲突）呢？这假定用户可以通过删除存储的资源来解决问题。

否则507（并非完全标准）也可能起作用。除非您通常将200用于错误，否则我不会使用200。

如果超出了客户端配额，则是服务器错误，在这种情况下，请避免使用5xx。