关于在设计 API 时的一个考虑

[Livid]

如果用户请求的时候提交了错误的参数，这个时候服务器端无法满足用户的需求，需要返回一个错误页面。

假设 API 是 JSON 格式的，那么大家做为开发者，会希望服务器端如何通知这个错误呢？

目前考虑的几种做法：

1. 返回 HTTP 400 Bad Request 状态。

2. 在所有的 JSON 反馈中都加入这样的设定：

{
"status" : "error"
}

或

{
"status" : "ok"
}

期待大家对这个问题的建议。

[adow]

我现在的做法是使用status code, 甚至在post/put操作成功时也使用 200/201/202，而正文中只输出正确操作数据的json格式

比如$.ajax在出错时直接在error:function(xhr)中进行处理，而不用每次在返回中判断是否正确的状态了。

类似 http://www.douban.com/service/apidoc/reference/common#返回状态说明

[leiz]

返回http status code + 自定义error code, 不需要返回错误信息，提前定义好error code对应的错误信息就行。把自定义的错误信息添加到返回里不太合适。

[freefcw]

还是带上error code比较好吧，msg这个东西有总比没有好

[guoquan]

400+错误信息

[Semon]

errorCode + errorMessage

[ultragtx]

1＋2吧

[ratazzi]

我比较倾向于后者，可以参考 jsonrpc2 的方式

[iwege]

最好是以共用的形式来做，两者并不冲突。

[runsheng2005]

通常采用 status 标示状态，再外加一个 errinfo 来标示错误信息！

[tox]

两种同时使用
1，http协议异常，或请求参数不符合，在http响应头加入错误码
2，JSON中得"status" : "error" 代表业务错误，如注册得时候用户名重复等类似这样得异常

[lqs]

注意，有些ISP会把非2xx的http response劫持成自己的广告页面。

[virushuo]

我比较喜欢foursquare的模式。

参考： https://developer.foursquare.com/overview/

[reorx]

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
"The request could not be understood by the server due to malformed syntax"

http://www.checkupdown.com/status/E400.html
"The Web server (running the Web site) thinks that the data stream sent by the client (e.g. your Web browser or our CheckUpDown robot) was 'malformed' i.e. did not respect the HTTP protocol completely. So the Web server was unable to understand the request and process it. "

虽然我自己也是用400,不过我一直对自己对400的理解有疑问。根据以上的描述，似乎400专指协议上有问题，即HTTP请求本身不能被server理解，而非HTTP请求被解析，但逻辑上的参数不正确的情况。

也许只是钻牛角尖吧，大家不用在意，毕竟各大网站使用多年了。

实际项目中和@cjou 用的是同样的方式。

[leben]

倾向于只要不是404错误，全部返回有意义的状态和信息。
如果status是error，最好有完整的错误信息。
这样不需要很完善的api使用文档，就可以比较顺利的使用api。

[levey]

一般是error code。。。

[ElmerZhang]

详细错误原因肯定要在body中写明的，格式可以是这样
{errno:xx, error:'', data:''}
errno为0时为成功，其他是失败。
也可以结合http状态码来做，但是不能错误全404，状态码一定要和错误的含义对的上，例如找不到对象是404，授权失败是401之类，写成功读成功用200，删除成功用204等等

[acen]

我统一返回200， json格式{success:true/false, data:xxx, msg:xxx}

[sobigfish]

api不是面向最终用户的 其实http状态码意义不大，而且js lib之类也不能很好的支持，所以还是json格式的错误代码比较有用。

[flowercold]

做过的一个快递查询类的api，对于此类情况，使用的是第2种办法

{"message":"EMS快递单号是由E开头的字母，CS/CN结尾的字母加上中间9位的数字组成的，请检查相关单号。","status":"0"}


"status"分几类情况，单号查询的数据源正常，单号查询的数据源异常，单号异常，单号正常暂无记录等等；

[bhuztez]

@sobigfish SOAP就是这么想的