幂简集成LOGO
API Hub
找服务商
API知识库
我是服务商
产品和服务
关于我们
控制台
所有WIKI > R字母 > RESTful API 状态码设计指南

RESTful API 状态码设计指南

2024-02-22

特别需要关注 HTTP 状态码，之所以把它单独拿出来，是因为状态码的解读非常多，也非常容易出错。由于状态码理解的不一致，产生了很多麻烦。

__案例一：__用户与提供者对’计费‘的一致性理解。有些用户会认为’200‘才会付费，其它状态码都不应该扣费，但API服务商不这么认为，它认为只要请求了服务器，产生了计算，就需要付费。

__案例二：__你的API返回一个带有`200 OK`状态码的错误响应。曾经我不得不集成一个API，它对每个响应都返回`200 OK`，并通过`status`字段来表示请求是否成功：

“`
{
“status”: “success”,
“data”: {}
}

“`

尽管HTTP状态码返回`200 OK`，但我不能完全确定它有没有处理我的请求失败。

实际上，[API](https://www.explinks.com/wiki/api/)可以返回如下响应：

“`
HTTP/1.1 400 Bad Request
Content-Type: application/json{
“error”: “Expected at least three items in the list.”
}
“`

## HTTP状态码

所有的 `API` 响应，`必须` 遵守 `HTTP` 设计规范，`必须` 选择合适的 `HTTP` 状态码。`一定不可` 所有接口都返回状态码为 `200` 的 `HTTP` 响应，如：

“`
HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com

{
“code”: 0,
“msg”: “success”,
“data”: {
“username”: “username”
}
}

“`

或

“`
HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com

{
“code”: -1,
“msg”: “该活动不存在”,
}

“`

下表列举了常见的 `HTTP` 状态码

| 状态码 | 描述 |
| — | — |
| 1xx | 代表请求已被接受，需要继续处理 |
| 2xx | 请求已成功，请求所希望的响应头或数据体将随此响应返回 |
| 3xx | 重定向 |
| 4xx | 客户端原因引起的错误 |
| 5xx | 服务端原因引起的错误 |

> 只有来自客户端的请求被正确的处理后才能返回 `2xx` 的响应，所以当 API 返回 `2xx` 类型的状态码时，前端 `必须` 认定该请求已处理成功。

必须强调的是，所有 `API“一定不可` 返回 `1xx` 类型的状态码。当 `API` 发生错误时，`必须` 返回出错时的详细信息。目前常见返回错误信息的方法有两种：

1、将错误详细放入 `HTTP` 响应首部；

“`
X-MYNAME-ERROR-CODE: 4001
X-MYNAME-ERROR-MESSAGE: Bad authentication token
X-MYNAME-ERROR-INFO: http://docs.example.com/api/v1/authentication

“`

2、直接放入响应实体中；

“`
HTTP/1.1 401 Unauthorized
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:02:59 GMT
Connection: keep-alive

{“error_code”:40100,”message”:”Unauthorized”}

“`

考虑到易读性和客户端的易处理性，我们 `必须` 把错误信息直接放到响应实体中，并且错误格式 `应该` 满足如下格式：

“`
{
“message”: “您查找的资源不存在”,
“error_code”: 404001
}

“`

其中错误码（`error_code`）`必须` 和 `HTTP` 状态码对应，也方便错误码归类，如：

“`
HTTP/1.1 429 Too Many Requests
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:15:52 GMT
Connection: keep-alive

{“error_code”:429001,”message”:”你操作太频繁了”}

“`

“`
HTTP/1.1 403 Forbidden
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:19:27 GMT
Connection: keep-alive

{“error_code”:403002,”message”:”用户已禁用”}

“`

`应该` 在返回的错误信息中，同时包含面向开发者和面向用户的提示信息，前者可方便开发人员调试，后者可直接展示给终端用户查看如：

“`
{
“message”: “直接展示给终端用户的错误信息”,
“error_code”: “业务错误码”,
“error”: “供开发者查看的错误信息”,
“debug”: [
“错误堆栈，必须开启 debug 才存在”
]
}

“`

下面详细列举了各种情况 API 的返回说明。

### 200 ok

`200` 状态码是最常见的 `HTTP` 状态码，在所有 __成功__ 的 `GET` 请求中，`必须` 返回此状态码。`HTTP` 响应实体部分 `必须` 直接就是数据，不要做多余的包装。

错误示例：

“`
HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com

{
“user”: {
“id”:1,
“nickname”:”fwest”,
“username”: “example”
}
}

“`

正确示例：

1、获取单个资源详情

“`
{
“id”: 1,
“username”: “godruoyi”,
“age”: 88,
}

“`

2、获取资源集合

“`
[
{
“id”: 1,
“username”: “godruoyi”,
“age”: 88,
},
{
“id”: 2,
“username”: “foo”,
“age”: 88,
}
]

“`

3、额外的媒体信息

“`
{
“data”: [
{
“id”: 1,
“avatar”: “https://lorempixel.com/640/480/?32556”,
“nickname”: “fwest”,
“last_logined_time”: “2018-05-29 04:56:43”,
“has_registed”: true
},
{
“id”: 2,
“avatar”: “https://lorempixel.com/640/480/?86144”,
“nickname”: “zschowalter”,
“last_logined_time”: “2018-06-16 15:18:34”,
“has_registed”: true
}
],
“meta”: {
“pagination”: {
“total”: 101,
“count”: 2,
“per_page”: 2,
“current_page”: 1,
“total_pages”: 51,
“links”: {
“next”: “http://api.example.com?page=2”
}
}
}
}

“`

> 其中，分页和其他额外的媒体信息，必须放到 `meta` 字段中。

### 201 Created

当服务器创建数据成功时，`应该` 返回此状态码。常见的应用场景是使用 `POST` 提交用户信息，如：

– 添加了新用户
– 上传了图片
– 创建了新活动

等，都可以返回 `201` 状态码。需要注意的是，你可以选择在用户创建成功后返回新用户的数据

“`
HTTP/1.1 201 Created
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:13:40 GMT
Connection: keep-alive

{
“id”: 1,
“avatar”: “https://lorempixel.com/640/480/?32556”,
“nickname”: “fwest”,
“last_logined_time”: “2018-05-29 04:56:43”,
“created_at”: “2018-06-16 17:55:55”,
“updated_at”: “2018-06-16 17:55:55”
}

“`

也可以返回一个响应实体为空的 `HTTP Response` 如：

“`
HTTP/1.1 201 Created
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:12:20 GMT
Connection: keep-alive

“`

> 这里我们 `应该` 采用第二种方式，因为大多数情况下，客户端只需要知道该请求操作成功与否，并不需要返回新资源的信息。

### 202 Accepted

该状态码表示服务器已经接受到了来自客户端的请求，但还未开始处理。常用短信发送、邮件通知、模板消息推送等这类很耗时需要队列支持的场景中；

> 返回该状态码时，响应实体 `必须` 为空。

“`
HTTP/1.1 202 Accepted
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:25:15 GMT
Connection: keep-alive

“`

### 204 No Content

该状态码表示响应实体不包含任何数据，其中：

– 在使用 `DELETE` 方法删除资源 __成功__ 时，`必须` 返回该状态码
– 使用 `PUT`、`PATCH` 方法更新数据 __成功__ 时，也 `应该` 返回此状态码

“`
HTTP/1.1 204 No Content
Server: nginx/1.11.9
Date: Sun, 24 Jun 2018 09:29:12 GMT
Connection: keep-alive

“`

### 3xx 重定向

所有 `API“不该` 返回 `3xx` 类型的状态码。因为 `3xx` 类型的响应格式一般为下列格式：

“`
HTTP/1.1 302 Found
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 09:41:50 GMT
Location: https://example.com

“`

所有 `API“一定不可` 返回纯 `HTML` 结构的响应；若一定要使用重定向功能，`可以` 返回一个响应实体为空的 `3xx` 响应，并在响应头中加上 `Location` 字段:

“`
HTTP/1.1 302 Found
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:52:50 GMT
Location: https://godruoyi.com
Connection: keep-alive

“`

### 400 Bad Request

由于明显的客户端错误（例如，请求语法格式错误、无效的请求、无效的签名等），服务器 `应该` 放弃该请求。

> 当服务器无法从其他 4xx 类型的状态码中找出合适的来表示错误类型时，都 `必须` 返回该状态码。

“`
HTTP/1.1 400 Bad Request
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:22:36 GMT
Connection: keep-alive

{“error_code”:40000,”message”:”无效的签名”}

“`

### 401 Unauthorized

该状态码表示当前请求需要身份认证，以下情况都 `必须` 返回该状态码。

– 未认证用户访问需要认证的 API
– access_token 无效/过期

> 客户端在收到 `401` 响应后，都 `应该` 提示用户进行下一步的登录操作。

“`
HTTP/1.1 401 Unauthorized
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
WWW-Authenticate: JWTAuth
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:17:02 GMT
Connection: keep-alive

“message”:”Token Signature could not be verified.”,”error_code”: “40100”}

“`

### 403 Forbidden

该状态码可以简单的理解为没有权限访问该请求，服务器收到请求但拒绝提供服务。

如当普通用户请求操作管理员用户时，`必须` 返回该状态码。

“`
HTTP/1.1 403 Forbidden
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:05:34 GMT
Connection: keep-alive

{“error_code”:40301,”message”:”权限不足”}

“`

### 404 Not Found

该状态码表示用户请求的资源不存在，如

– 获取不存在的用户信息 （get /users/9999999）
– 访问不存在的端点

都 `必须` 返回该状态码，若该资源已永久不存在，则 `应该` 返回 `401` 响应。

### 405 Method Not Allowd

当客户端使用的 `HTTP` 请求方法不被服务器允许时，`必须` 返回该状态码。

> 如客户端调用了 `POST` 方法来访问只支持 GET 方法的 API

该响应 `必须` 返回一个 `Allow` 头信息用以表示出当前资源能够接受的请求方法的列表。

“`
HTTP/1.1 405 Method Not Allowed
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Allow: GET, HEAD
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:30:57 GMT
Connection: keep-alive

{“message”:”405 Method Not Allowed”,”error_code”: 40500}

“`

### 406 Not Acceptable

`API` 在不支持客户端指定的数据格式时，应该返回此状态码。如支持 `JSON` 和 `XML` 输出的 `API` 被指定返回 `YAML` 格式的数据时。

> Http 协议一般通过请求首部的 Accept 来指定数据格式

### 408 Request Timeout

客户端请求超时时 `必须` 返回该状态码，需要注意的时，该状态码表示 __客户端请求超时__，在涉及第三方 `API`调用超时时，`一定不可` 返回该状态码。

### 409 Gonfilct

该状态码表示因为请求存在冲突无法处理。如通过手机号码提供注册功能的 `API`，当用户提交的手机号已存在时，`必须` 返回此状态码。

“`
HTTP/1.1 409 Conflict
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:19:04 GMT
Connection: keep-alive

{“error_code”:40900,”message”:”手机号已存在”}

“`

### 410 Gone

和 `404` 类似，该状态码也表示请求的资源不存在，只是 `410` 状态码进一步表示所请求的资源已不存在，并且未来也不会存在。在收到 `410` 状态码后，客户端 `应该` 停止再次请求该资源。

### 413 Request Entity Too Large

该状态码表示服务器拒绝处理当前请求，因为该请求提交的实体数据大小超过了服务器愿意或者能够处理的范围。

> 此种情况下，服务器可以关闭连接以免客户端继续发送此请求。

如果这个状况是临时的，服务器 `应该` 返回一个 `Retry-After` 的响应头，以告知客户端可以在多少时间以后重新尝试。

### 414 Request-URI Too Long

该状态码表示请求的 `URI` 长度超过了服务器能够解释的长度，因此服务器拒绝对该请求提供服务。

### 415 Unsupported Media Type

通常表示服务器不支持客户端请求首部 `Content-Type` 指定的数据格式。如在只接受 `JSON` 格式的 `API` 中放入 `XML` 类型的数据并向服务器发送，都 `应该` 返回该状态码。

该状态码也可用于如：只允许上传图片格式的文件，但是客户端提交媒体文件非法或不是图片类型，这时 `应该`返回该状态码：

“`
HTTP/1.1 415 Unsupported Media Type
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:09:40 GMT
Connection: keep-alive

{“error_code”:41500,”message”:”不允许上传的图片格式”}

“`

### 429 Too Many Request

该状态码表示用户请求次数超过允许范围。如 `API` 设定为 `60次/分钟`，当用户在一分钟内请求次数超过 60 次后，都 `应该` 返回该状态码。并且也 `应该` 在响应首部中加上下列头部：

“`
X-RateLimit-Limit: 10 请求速率（由应用设定，其单位一般为小时/分钟等，这里是 10次/5分钟）
X-RateLimit-Remaining: 0 当前剩余的请求数量
X-RateLimit-Reset: 1529839462 重置时间
Retry-After: 120 下一次访问应该等待的时间（秒）

“`

列子

“`
HTTP/1.1 429 Too Many Requests
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1529839462
Retry-After: 290
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 11:19:32 GMT
Connection: keep-alive

{“message”:”You have exceeded your rate limit.”,”error_code”:42900}

“`

`必须` 为所有的 API 设置 Rate Limit 支持。

### 500 Internal Server Error

该状态码 `必须` 在服务器出错时抛出，对于所有的 `500` 错误，都 `应该` 提供完整的错误信息支持，也方便跟踪调试。

### 503 Service Unavailable

该状态码表示服务器暂时处理不可用状态，当服务器需要维护或第三方 `API` 请求超时/不可达时，都 `应该` 返回该状态码，其中若是主动关闭 API 服务，`应该`在返回的响应首部加上 `Retry-After` 头部，表示多少秒后可以再次访问。

“`
HTTP/1.1 503 Service Unavailable
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:56:20 GMT
Retry-After: 60
Connection: keep-alive

{“error_code”:50300,”message”:”服务维护中”}

“`

其他 `HTTP` 状态码请参考 HTTP 状态码- 维基百科。

## 参考资料

原文: 《[RESTful 设计规范](https://godruoyi.com/posts/the-resetful-api-design-specification)》
[HTTP 状态码- 维基百科](https://zh.wikipedia.org/zh-hans/HTTP%E7%8A%B6%E6%80%81%E7%A0%81)
一站搜索、试用、比较全球API！
幂简集成已收录 5531种API!
试用API，一次比较多个渠道