常用状态码

  • 200 OK [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
  • 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
  • 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
  • 204 NO CONTENT - [DELETE]：用户删除数据成功。
  • 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
  • 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
  • 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
  • 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
  • 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
  • 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
  • 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
  • 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

HTTP状态码

REST API使用HTTP响应消息的Status-Line部分来通知客户端其请求的总体结果。RFC 2616定义了Status-Line语法，如下所示：

Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF

HTTP定义了四十个标准状态代码，可用于传达客户端请求的结果。状态代码分为以下五个类别。

类别 描述
1xx：信息 通信传输协议级信息。
2xx：成功 表示客户端的请求已成功接受。
3xx：重定向 表示客户端必须执行一些其他操作才能完成其请求。
4xx：客户端错误 此类错误状态代码指向客户端。
5xx：服务器错误 服务器负责这些错误状态代码。

现在看一下特别适用于REST API设计的代码子集 - 更详细一些。

200（OK）

它表示REST API成功执行了客户端请求的任何操作，并且2xx系列中没有更具体的代码是合适的。

与204状态代码不同，200响应应包括响应主体。响应返回的信息取决于请求中使用的方法，例如：

  • 在响应中发送GET对应于所请求资源的实体;
  • HEAD对应于所请求资源的实体头字段在响应中发送而没有任何消息体;
  • POST一个描述或包含行动结果的实体;
  • 跟踪包含终端服务器接收的请求消息的实体。

201（创建）

只要在集合内创建资源，REST API就会使用201状态代码进行响应。由于某些控制器动作，有时可能会创建新资源，在这种情况下，201也是适当的响应。

新创建的资源可以由响应实体中返回的URI引用，其中由Location头字段给出的资源的最具体URI。

原始服务器必须在返回201状态代码之前创建资源。如果无法立即执行操作，服务器应该响应202（已接受）响应。

202（已接受）

202响应通常用于需要很长时间才能处理的操作。它表示该请求已被接受处理，但处理尚未完成。该请求可能会或可能不会最终被执行，甚至可能在处理时不允许。

其目的是允许服务器接受对某些其他进程的请求（可能是每天只运行一次的面向批处理的进程），而不要求用户代理与服务器的连接持续到进程完成为止。

使用此响应返回的实体应该包括请求的当前状态的指示以及指向状态监视器的指针（作业队列位置）或某个用户何时可以期望满足请求的估计。

203

请求的代理服务器修改了源服务器返回的 200 中的内容，一般用不到。比如说，我们通过代理服务器向服务器 A 请求用户信息，服务器 A 正常响应，但代理服务器命中了缓存并返回了自己的缓存内容，这时候它返回 203 告诉我们这部分信息不一定是最新的，我们可以自行判断并处理。

204（无内容）

在204个状态的代码通常是响应发送到一个PUT，POST或DELETE当REST API拒绝发送回在响应消息的主体的任何状态消息或表示请求。

API还可以结合GET请求发送204以指示所请求的资源存在，但是没有要包括在正文中的状态表示。

如果客户端是用户代理，它不应该从导致请求发送的文档视图中更改它的文档视图。此响应主要用于允许在不导致更改用户代理的活动文档视图的情况下进行操作的输入，尽管任何新的或更新的元信息应该应用于当前在用户代理的活动视图中的文档。

204响应绝不能包含消息体，因此总是在头字段之后的第一个空行终止。

205

类似 204，但是要求请求者重置视图，一般也用不到。比如说，我们请求删除某个用户，服务器返回 205 的话，我们就刷新现在的用户列表。

206

请求成功，但根据请求头只返回了部分内容。比如说，我们下载一部片，共有 10 部分，我们把请求也分成了 10 次（防止一次请求过大），这时候服务器就可以返回 206 并在其头部告诉我们这是哪一部分，然后再根据这个信息进行拼装。

300

请求成功，但结果有多种选择。比如说，我们下载一部片，服务器有 avi、mp4 等格式，这时候可以返回 300，并在 body 里告知有哪些格式，然后用户可以根据这些格式再次请求。

301（永久移动）

301状态代码表示REST API的资源模型已经过重新设计，并且已为客户端请求的资源分配了新的永久URI。REST API应在响应的Location头中指定新的URI，并且所有将来的请求都应该定向到给定的URI。

您很难在API中使用此响应代码，因为您始终可以使用API版本控制新API，同时保留旧API。

302（找到）

HTTP响应状态代码302 Found是执行URL重定向的常用方式。具有此状态代码的HTTP响应还将在位置标头字段中提供URL。通过具有该代码的响应来邀请用户代理（例如，web浏览器），以对位置字段中指定的新URL做出第二个（否则相同的）请求。

许多Web浏览器以违反此标准的方式实现此代码，将新请求的请求类型更改为GET，而不管原始请求中使用的类型（例如POST）。RFC 1945和RFC 2068指定不允许客户端更改重定向请求上的方法。已经为希望明确清楚客户端期望哪种反应的服务器添加了状态代码303和307。

303（见其他）

303响应表示控制器资源已完成其工作，但它不是发送可能不需要的响应主体，而是向客户端发送响应资源的URI。这可以是临时状态消息的URI，也可以是某些已存在的，更永久的资源的URI。

一般而言，303状态代码允许REST API发送对资源的引用，而不强制客户端下载其状态。相反，客户端可以向Location头的值发送GET请求。

303响应绝不能被缓存，但对第二个（重定向）请求的响应可能是可缓存的。

304（未修改）

此状态代码类似于204（“无内容”），因为响应正文必须为空。关键的区别在于，当在正文中没有要发送的内容时使用204，而在自请求头If-Modified-Since或If-None-Match指定的版本以来未对资源进行修改时使用304。

在这种情况下，不需要重新传输资源，因为客户端仍然具有先前下载的副本。

使用它可以在服务器和客户端上节省带宽和重新处理，因为与服务器重新处理的整个页面相比，必须仅发送和接收标头数据，然后使用服务器和客户端的更多带宽再次发送。

305

请求的资源必须通过代理访问。比如说，我们想请求服务器 A 上新的 iPhone 的信息，但是需要通过代理服务器才能访问，如果直接请求了服务器 A，没有经过代理服务器，这时候服务器 A 就可以返回 305 从而告诉我们应当访问代理服务器。

306

不用了。

307（临时重定向）

类似 302，但要求使用原有的请求方式来通过新地址获取资源。

307响应表明REST API不会处理客户端的请求。相反，客户端应该将请求重新提交到响应消息的Location头指定的URI。但是，将来的请求仍应使用原始URI。

REST API可以使用此状态代码为客户端请求的资源分配临时URI。例如，307响应可用于将客户端请求转移到另一个主机。

临时URI应该由响应中的Location字段给出。除非请求方法是HEAD，否则响应的实体应该包含一个带有指向新URI的超链接的短超文本注释。如果收到307状态代码以响应除GETor 之外的请求HEAD，则用户代理不得自动重定向请求，除非用户可以确认，因为这可能会改变发出请求的条件。

308

类似 301，但要求使用原有的请求方式来通过新地址获取资源。

400（不良请求）

400是通用客户端错误状态，在没有其他4xx错误代码适用时使用。错误可能类似于格式错误的请求语法，无效的请求消息参数或欺骗性请求路由等。

客户端不应该在没有修改的情况下重复请求。

401（未经授权）

401错误响应表示客户端尝试在受保护资源上运行而未提供适当的授权。它可能提供了错误的凭据或根本没有。响应必须包含WWW-Authenticate头字段，其中包含适用于所请求资源的质询。

客户端可以使用合适的Authorization头字段重复请求。如果请求已包含授权凭据，则401响应表示已拒绝授权这些凭据。如果401响应包含与先前响应相同的挑战，并且用户代理已经尝试过至少一次认证，则应该向用户呈现响应中给出的实体，因为该实体可能包括相关的诊断信息。

402

为将来的需要所保留的状态码。

403（禁止）

403错误响应表明客户端的请求是正确形成的，但REST API拒绝遵守它，即用户没有资源的必要权限。403响应不是客户端凭证不足的情况; 这将是401（“未经授权”）。

身份验证无济于事，请求不应重复。与401 Unauthorized响应不同，身份验证不会产生任何影响。

404（未找到）

404错误状态代码表示REST API无法将客户端的URI映射到资源，但可能在将来可用。客户的后续请求是允许的。

没有说明该病症是暂时的还是永久性的。如果服务器通过一些内部可配置的机制知道旧资源永久不可用且没有转发地址，则应该使用410（Gone）状态代码。当服务器不希望确切地说明请求被拒绝的原因，或者没有其他响应适用时，通常会使用此状态代码。

405（不允许的方法）

API响应405错误以指示客户端尝试使用资源不允许的HTTP方法。例如，只读资源只能支持GET和HEAD，而控制器资源可能只允许GET和POST，但不支持PUT或DELETE。

405响应必须包含Allow标头，该标头列出资源支持的HTTP方法。例如：

允许：GET，POST

406（不可接受）

406错误响应表示API无法生成任何客户端的首选媒体类型，如Accept请求标头所示。例如，application/xml如果API仅愿意将数据格式化，则客户端对格式化的数据的请求将接收406响应application/json。

如果响应可能是不可接受的，则用户代理应该暂时停止接收更多数据并查询用户以决定进一步的操作。

407

类似 401，但是要求必须去同代理服务器进行认证。

408

客户端请求超时。我们想 POST 创建一个用户，虽然建立了连接，但是网络不好，服务器在规定时间内没有得到我们的请求信息，这时候服务器可以返回 408 告诉我们超时了。然后我们可以重新发送请求。

409

请求冲突。比如说，服务器要求不同用户不能重名，服务器已经有了一个名叫小伟的用户，这时候我们又想创建一个名叫小伟的用户，服务器可以返回 409，告诉我们冲突了，也可以在 body 中明确告知是什么冲突了。

410

请求资源曾经存在，但现在不存在了。比如说，我们下载葫芦娃，但是因为版权被删了，下载不了了，这时候服务器返回 410，告诉我们洗洗早点睡。

411

没有提供请求资源的长度。比如说，我们下载葫芦娃，服务器只允许我们分部分下载，我们如果不告诉服务器我们要下载哪部分，服务器就返回 411 警告我们。

412（前提条件失败）

412错误响应表明客户端在其请求标头中指定了一个或多个前提条件，有效地告诉REST API仅在满足某些条件时才执行其请求。412响应表示不满足这些条件，因此API不发送请求，而是发送此状态代码。

413

请求体过大。比如说，服务器要求上传文件不能超过 5M，但是我们 POST 了 10M，这时候就返回 413。

414

请求的 URI 太长了。比如说，我们提供了太多的 Query 参数，以至于超过了服务器的限制，这时候可以返回 414。

415（不支持的媒体类型）

415错误响应表明API无法处理客户端提供的媒体类型，如Content-Type请求标头所示。例如，application/xml如果API仅愿意处理格式化为的数据，则包括格式化的数据的客户机请求将接收415响应application/json。

例如，客户端将图像上载为image / svg + xml，但服务器要求图像使用不同的格式。

416

请求的区间无效。比如说，我们分部分下载时请求葫芦娃的 10 分钟到 12 分钟的内容，但是这部葫芦娃只有 1 分钟的内容，这时候就返回 416。

417

预期错误。指服务器没法满足我们在请求头里的 Expect 相关的信息。

500内部服务器错误）

500是通用REST API错误响应。大多数Web框架在执行一些引发异常的请求处理程序代码时会自动响应此响应状态代码。

500错误绝不是客户端的错误，因此客户端重试触发此响应的完全相同的请求是合理的，并希望获得不同的响应。

API响应是一般错误消息，在遇到意外情况且没有更合适的消息时给出。

501（未实施）

服务器要么无法识别请求方法，要么无法满足请求。通常，这意味着将来的可用性（例如，Web服务API的新功能）。

502

网关错误。比如说，我们向服务器 A 请求下载葫芦娃，但是 A 其实只是一个代理服务器，他得向 B 请求葫芦娃，但是不知道为啥 B 不理他或者给他错误，这时候哦可以 A 返回 502 用来表示 B 这家伙傲娇了。

503

服务暂时不可用。比如说，服务器正好在更新代码重启。

504

类似 502，但是这时候是 B 不理 A，超时了 。

505

请求的 HTTP 版本不支持。比如说，现在强行根据 HTTP 1000 来请求。

HTTP协议常用标准状态码含义

状态码 含义 备注
200 请求已完成 2XX状态码均为正常状态码返回。
300 多种选择 服务器根据请求可执行多种操作。服务器可根据请求者 (User agent) 来选择一项操作，或提供操作列表供请求者选择。
301 永久移动 请求的网页已被永久移动到新位置。服务器返回此响应（作为对 GET 或 HEAD 请求的响应）时，会自动将请求者转到新位置。您应使用此代码通知 Googlebot 某个网页或网站已被永久移动到新位置。
302 临时移动 服务器目前正从不同位置的网页响应请求，但请求者应继续使用原有位置来进行以后的请求。此代码与响应 GET 和 HEAD 请求的 301 代码类似，会自动将请求者转到不同的位置。
303 查看其他位置 当请求者应对不同的位置进行单独的 GET 请求以检索响应时，服务器会返回此代码。对于除 HEAD 请求之外的所有请求，服务器会自动转到其他位置。
304 未修改 自从上次请求后，请求的网页未被修改过。服务器返回此响应时，不会返回网页内容。
305 使用代理 请求者只能使用代理访问请求的网页。如果服务器返回此响应，那么，服务器还会指明请求者应当使用的代理。
400 错误请求 服务器不理解请求的语法。
401 未授权 请求要求进行身份验证。登录后，服务器可能会对页面返回此响应。
403 已禁止 服务器拒绝请求。
404 未找到 服务器找不到请求的网页。例如，如果请求是针对服务器上不存在的网页进行的，那么，服务器通常会返回此代码。
405 方法禁用 禁用请求中所指定的方法。
406 不接受 无法使用请求的内容特性来响应请求的网页。
407 需要代理授权 此状态代码与401（未授权）类似，但却指定了请求者应当使用代理进行授权。如果服务器返回此响应，那么，服务器还会指明请求者应当使用的代理。
408 请求超时 服务器等候请求时超时。
409 冲突 服务器在完成请求时发生冲突。服务器的响应必须包含有关响应中所发生的冲突的信息。服务器在响应与前一个请求相冲突的PUT请求时可能会返回此代码，同时会提供两个请求的差异列表。
411 需要有效长度 服务器不会接受包含无效内容长度标头字段的请求。
412 未满足前提条件 服务器未满足请求者在请求中设置的其中一个前提条件。
413 请求实体过大 服务器无法处理请求，因为请求实体过大，已超出服务器的处理能力。
414 请求的URI过长 请求的URI（通常为网址）过长，服务器无法进行处理。
415 不支持的媒体类型 请求的格式不受请求页面的支持。
416 请求范围不符合要求 如果请求是针对网页的无效范围进行的，那么，服务器会返回此状态代码。
417 未满足期望值 服务器未满足期望请求标头字段的要求。
499 客户端断开连接 因服务端处理时间过长，客户端关闭了连接。
500 服务器内部错误 服务器遇到错误，无法完成请求。
501 尚未实施 服务器不具备完成请求的功能。例如，当服务器无法识别请求方法时，服务器可能会返回此代码。
502 错误网关 服务器作为网关或代理，从上游服务器收到了无效的响应。
503 服务不可用 目前无法使用服务器（由于超载或进行停机维护）。通常，这只是一种暂时的状态。
504 网关超时 服务器作为网关或代理，未及时从上游服务器接收请求。
505 HTTP版本不受支持 服务器不支持请求中所使用的HTTP协议版本。

参考文献：
https://tools.ietf.org/html/rfc7231
https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

文档更新时间: 2024-03-25 11:24   作者：姚连洲