错误代码¶

Jarvis API 自 v2.0.1 起使用 RESTful 的开发规范，使用 HTTP 的状态码返回接口调用的结果。一般会使用 2xx 来表示调用成功， 4xx 表示业务相关的失败，会有非常罕见的在调用过程中返回 5xx 的情况，表示 Jarvis 服务器暂时不可用。

通常情况下，未授权有两种错误状态码： 401 常发生在登录失败或者 token 失效的情况。例如 401 Unauthorized Access 。 403 常发生在用户已经登录并且 token 有效，但没有权限的情况，传递的 app_token 不正确也会返回该状态码。

HTTP 状态码¶

状态码	描述	说明
200	OK	服务器成功返回用户请求的数据
201	CREATED	服务器成功创建用户请求的纪录，通常出现在 POST/PUT/PATCH 操作中
202	Accepted	服务器成功接收用户的请求，但还没有请求结果，通常出现在异步处理的请求中
204	NO CONTENT	服务器成功处理用户的请求，但没有返回内容，通常出现在 DELETE 操作中
400	INVALID REQUEST	用户发出的请求有错误，通常为参数不符合 API 规则
401	Unauthorized	用户没有权限，通常出现在登录失败或者 token、app_token 错误的情况
403	Forbidden	用户登录成功，但是没有该操作的权限
404	NOT FOUND	用户发出的请求不存在，该响应可能是请求的记录或者请求的页面不存在，具体参考详细的错误码
5xx	INTERNAL SERVER ERROR	服务器内部错误，出现该错误的几率很低，但如果出现该错误说明 Jarvis 服务器目前不可用

失败响应

{
    "return_code": 20210,
    "message": "param length error"
}

虽然可以使用状态码来判断调用 Jarvis 是否成功，但状态码并不会显示所有的错误类型，例如 API 返回了 400 ，但并不能说明具体是哪个请求参数有问题，针对这种情况，Jarvis 会在调用失败的响应体中给出一段 json 代码描述更详细的错误类型。

Jarvis 的自定义错误响应代码包括 5位 的 return_code ，及简单的描述信息 message 用来描述错误发生的原因。

名称	类型	描述
return_code	Integer	自定义错误返回码
message	String	自定义错误信息描述

错误代码中的 message 只是为每一个错误给调用方提供一个简单的解释，Jarvis 不推荐将 message 的内容直接显示给终端用户。

使用 return_code 区分不同类型的错误并显示自定义的文本给终端用户或舍弃不重要的错误码是我们推荐的方法。

在 JMan 的 v2.0.2 开始，return_code 以 5 位数字表示具体接口错误的类型，前三位表示某个 API 的编号，每个接口的错误／正确信息的前三位都不变。后两位表示具体的错误类型，00-09 表示正确信息，10-99 表示错误信息。

例如：10001 表示接口 service-keys 申请 skey 成功的信息。 10010 表示申请 skey 时用户不是 SUser 的错误信息。

每个接口都有通用的正确和错误信息，如 token 失效等。通用正确信息的错误码前三位为 900，后两位使用 00-99 表示最多 100 种具体的错误类型。错误信息的错误码前三位为 901 ，后两位使用 00-99 表示最多 100 种具体的错误类型。

在 Jarvis 系统中使用到的所有不包含任何业务逻辑的通用型错误。

返回码	返回信息
90100	user info from get/post form/arg error - 用户信息参数不符合规则
90101	user info from flask g error - 读取用户信息失败，状态码 `500`
90102	user not found parse by token - token 不存在

Jarvis 服务器有可能短时间会出现 5xx 类型的状态码，出现这种错误多数是调用端无法自行解决的错误，需要 Jarvis 的管理员处理。

返回码	返回信息
30018	param configuration error, please contact the administrator - Jarvis 服务器配置错误