RESTful实践：如何设计API的错误消息

现有情况

发现不少RESTful API的错误代码都是用HTTP的状态码(Status Code)做为API的错误代码，公司的一些产品也是如此，以下图所示：

这种设计基本是把错误代码依次映射到HTTP的状态码上，HTTP协议中定义的状态码基本包含下面几类：

• 1xx Informational
• 2xx Success
• 3xx Redirection
• 4xx Client Error
• 5xx Server Error

好比对一个常见的新增用户的API，返回的Code会设计以下：

• 201 建立成功
• 400 请求错误（验证不经过，输入错误）
• 401 操做未受权
• 409 用户已存在

这种设计虽然能够覆盖大多数的状况，但对于一些业务逻辑错的话，就没有对应的HTTP状态码匹配了。好比，新增用户的时候，发现用户组人数已经达到上限了，给一个什么样的状态码呢？或者发现数据库没法访问了，又给一个什么状态码呢？

HTTP状态码是HTTP协议的一部分，应用层的API是不该该知道下层协议的细节的。假若有其余的业务错误没法对应上现有的HTTP状态码，岂不是还的本身扩展出更多的状态码？这样也会致使HTTP状态码和业务耦合，不管是服务端仍是客户端。

设计方案

个人设计方案是，全部RESTful Web Service返回结果的结构都相同，不考虑改变HTTP返回的状态吗，而只是在返回结果中代表状态和错误信息，大体结构以下：

{success:true|false, data:[]|{} [, error_code:, error_message:] } 经过success字段来代表这个请求的成功或失败；若是成功，则能够读取data数据进行后续处理；若是失败，能够读取error_code和error_message进行错误的处理。这样的好处就是，既不用关心HTTP状态码，也不用对成功或失败来处理不一样的JSON结构。

一些常见的设计

• Facebook

自定义错误代码，HTTP状态码统一为200。 { "error": { "message": "(#803) Some of the aliases you requested do not exist: me1", "type": "OAuthException", "code": 803 } }

• 新浪 使用自定义错误代码，错误的HTTP状态码是400。 http://open.weibo.com/wiki/Error_code

• 腾讯 使用自定义错误代码，错误的HTTP状态码统一是200。 http://wiki.open.qq.com/wiki/%E5%85%AC%E5%85%B1%E8%BF%94%E5%9B%9E%E7%A0%81%E8%AF%B4%E6%98%8E

• 阿里巴巴

自定义错误代码，不须要关心HTTP状态码 { "error_code":"450", "error_message":"Required argument memberId : expect [type: java.lang.String]", "exception":"Required argument memberId : expect [type: java.lang.String]" }