HTTP 应答中，需要带一个很重要的字段：status code。它说明了请求的大致情况，是否正常完成、需要进一步处理、出现了什么错误，对于客户端非常重要。状态码都是三位的整数，大概分成了几个区间：

2XX：请求正常处理并返回

3XX：重定向，请求的资源位置发生变化

4XX：客户端发送的请求有错误

5XX：服务器端错误

在 HTTP API 设计中，经常用到的状态码以及它们的意义如下表：

状态码 Label 解释

200 OK 请求成功接收并处理，一般响应中都会有 body

201 Created 请求已完成，并导致了一个或者多个资源被创建，最常用在 POST 创建资源的时候

202 Accepted 请求已经接收并开始处理，但是处理还没有完成。一般用在异步处理的情况，响应 body 中应该告诉客户端去哪里查看任务的状态

204 No Content 请求已经处理完成，但是没有信息要返回，经常用在 PUT 更新资源的时候（客户端提供资源的所有属性，因此不需要服务端返回）。如果有重要的 metadata，可以放到头部返回

301 Moved Permanently 请求的资源已经永久性地移动到另外一个地方，后续所有的请求都应该直接访问新地址。服务端会把新地址写在 Location 头部字段，方便客户端使用。允许客户端把 POST 请求修改为 GET。

304 Not Modified 请求的资源和之前的版本一样，没有发生改变。用来缓存资源，和条件性请求（conditional request）一起出现

307 Temporary Redirect 目标资源暂时性地移动到新的地址，客户端需要去新地址进行操作，但是不能修改请求的方法。

308 Permanent Redirect 和 301 类似，除了客户端不能修改原请求的方法

400 Bad Request 客户端发送的请求有错误（请求语法错误，body 数据格式有误，body 缺少必须的字段等），导致服务端无法处理

401 Unauthorized 请求的资源需要认证，客户端没有提供认证信息或者认证信息不正确

403 Forbidden 服务器端接收到并理解客户端的请求，但是客户端的权限不足。比如，普通用户想操作只有管理员才有权限的资源。

404 Not Found 客户端要访问的资源不存在，链接失效或者客户端伪造 URL 的时候回遇到这个情况

405 Method Not Allowed 服务端接收到了请求，而且要访问的资源也存在，但是不支持对应的方法。服务端必须返回 Allow 头部，告诉客户端哪些方法是允许的

415 Unsupported Media Type 服务端不支持客户端请求的资源格式，一般是因为客户端在 Content-Type 或者Content-Encoding 中申明了希望的返回格式，但是服务端没有实现。比如，客户端希望收到 xml返回，但是服务端支持 Json

429 Too Many Requests 客户端在规定的时间里发送了太多请求，在进行限流的时候会用到

500 Internal Server Error 服务器内部错误，导致无法完成请求的内容

503 Service Unavailable 服务器因为负载过高或者维护，暂时无法提供服务。服务器端应该返回 Retry-After 头部，告诉客户端过一段时间再来重试

上面这些状态码覆盖了 API 设计中大部分的情况，如果对某个状态码不清楚或者希望查看更完整的列表，可以参考 HTTP Status Code 这个网站，或者  的内容。

9. 错误处理：给出详细的信息

如果出错的话，在 response body 中通过 message 给出明确的信息。

比如客户端发送的请求有错误，一般会返回 4XX Bad Request 结果。这个结果很模糊，给出错误 message 的话，能更好地让客户端知道具体哪里有问题，进行快速修改。

如果请求的 JSON 数据无法解析，会返回 Problems parsing JSON

如果缺少必要的 filed，会返回 422 Unprocessable Entity，除了 message 之外，还通过errors 给出了哪些 field 缺少了，能够方便调用方快速排错

基本的思路就是尽可能提供更准确的错误信息：比如数据不是正确的 json，缺少必要的字段，字段的值不符合规定…… 而不是直接说“请求错误”之类的信息。

10. 验证和授权

一般来说，让任何人随意访问公开的 API 是不好的做法。验证和授权是两件事情：

验证（Authentication）是为了确定用户是其申明的身份，比如提供账户的密码。不然的话，任何人伪造成其他身份（比如其他用户或者管理员）是非常危险的

授权（Authorization）是为了保证用户有对请求资源特定操作的权限。比如用户的私人信息只能自己能访问，其他人无法看到；有些特殊的操作只能管理员可以操作，其他用户有只读的权限等等

如果没有通过验证（提供的用户名和密码不匹配，token 不正确等），需要返回 401 Unauthorized状态码，并在 body 中说明具体的错误信息；而没有被授权访问的资源操作，需要返回 403 Forbidden 状态码，还有详细的错误信息。

NOTE：Github API 对某些用户未被授权访问的资源操作返回 404 Not Found，目的是为了防止私有资源的泄露（比如黑客可以自动化试探用户的私有资源，返回 403 的话，就等于告诉黑客用户有这些私有的资源）。

11. 限流 rate limit

如果对访问的次数不加控制，很可能会造成 API 被滥用，甚至被 DDos 攻击。根据使用者不同的身份对其进行限流，可以防止这些情况，减少服务器的压力。

对用户的请求限流之后，要有方法告诉用户它的请求使用情况，Github API 使用的三个相关的头部：

X-RateLimit-Limit: 用户每个小时允许发送请求的最大值

X-RateLimit-Remaining：当前时间窗口剩下的可用请求数目

X-RateLimit-Rest: 时间窗口重置的时候，到这个时间点可用的请求数量就会变成X-RateLimit-Limit 的值