api的错误码该怎么设计

jflame
  • 1.8k

错误码应该是几位数?数字是多少?

看了看新浪、百度之类的api错误码,似乎没什么共同点啊
这方面有没有什么规范啊,全靠拍脑子想吗?望解惑啊!

回复
阅读 31.1k
11 个回答
✓ 已被采纳

如果走REST的话可以把状态码放到HTTP响应状态码里面,同时尽可能的遵从HTTP状态码规范。

如果直接在接口的返回值里面规定状态码的话,我个人的习惯是:正常为0,并且返回数据里面不需要错误描述字段了;其他数值表示为错误,并且带有简单的错误描述字段。错误码的数值在规定的时候把统一类型的错误放到相近的一段值上,比如这样:

SUCCESS = 0;    // 请求成功

// 用户方面错误1xxx
USERNAME_ERROR = 1000;    // 用户名错误
PASSWORD_ERROR = 1001;    // 用户密码错误
//....

// 资源错误2xxx
RESOURCE_EXPIRE = 2000;    // 资源过期
RESOURCE_NOTFOUND = 2001;    // 资源不存在
// ....

可以用状态码(http code) + 错误码(error code)来进行控制

1)状态码用来表示此次请求的结果是成功还是失败
200 - OK
400 - BadRequest
500 - Server Error
...

2) 错误码用来表示失败的具体的原因是什么,也可以理解为返回的验证信息
0 - 没有错误
1 - 用户名称不能为空
2 - 不合法的媒体文件类型
...

单一用哪一个来控制都是不完整的

其实我觉得错误码也并不是一个很好的机制,一般客户端拿到服务器返回错误码也要根据错误码提示对应的消息,既然服务器能预先定义错误码,不如发生对应的错误直接提示友好的错误消息,客户端那还能省点事。

如果是RESTful风格的API,就是用HTTP的状态码作为返回码;
如果只是简单的HTTP+JSON的API,需要在返回的JSON里面写例如{"code": 1, "msg": "parameter invalid"}之类的信息。
最重要的是:需要在文档中设计一份返回码和错误含义的列表。这份列表可以是整个项目一套,也可以是一个API一套。code的范围可以自己定,但一般0都表示成功。

harryxu
  • 1
新手上路,请多包涵

我一般就是直接使用http的状态码。

引用一下我正在翻译的 HTTP API 设计指南

返回合适的状态码

为每一次的响应返回合适的HTTP状态码. 好的响应应该使用如下的状态码:

  • 200: GET请求成功, 及DELETEPATCH同步请求完成,或者PUT同步更新一个已存在的资源
  • 201: POST 同步请求完成,或者PUT同步创建一个新的资源
  • 202: POST, PUT, DELETE, 或 PATCH 请求接收,将被异步处理
  • 206: GET 请求成功, 但是只返回一部分,参考:上文中范围分页

使用身份认证(authentication)和授权(authorization)错误码时需要注意:

  • 401 Unauthorized: 用户未认证,请求失败
  • 403 Forbidden: 用户无权限访问该资源,请求失败

当用户请求错误时,提供合适的状态码可以提供额外的信息:

  • 422 Unprocessable Entity: 请求被服务器正确解析,但是包含无效字段
  • 429 Too Many Requests: 因为访问频繁,你已经被限制访问,稍后重试
  • 500 Internal Server Error: 服务器错误,确认状态并报告问题

对于用户错误和服务器错误情况状态码,参考: HTTP response code spec

lonso
  • 1
新手上路,请多包涵

其实错误码用http状态码就可以了,
主要是错误消息的提示需要规范设计.
你所说的错误码应该是http状态码错误情况返回信息里面的错误码?

这个完全看设计者,比如成功状态为1,错误状态都是负值,第一个错误就是-1,第二个错误-2,每次设计新的接口就需要定义新的错误,依次累加就行

我也是参考微信的全局返回码,以Http+JSON作为应答消息
格式为:{"errCode": code, "errMsg": "msg", "data": {}}
code 习惯上去0为success, -1 为fail,其它是 模块号+错误号拼装

你知道吗?

宣传栏