Yii 2.0 的预定义的 HTTP 异常类的中文翻译与注解(参考:MDN、维基百科)

1、yii\web\BadRequestHttpException:状态码 400。

BadRequestHttpException represents a “Bad Request” HTTP exception with status code 400.

Use this exception to represent a generic client error. In many cases, there may be an HTTP exception that more precisely describes the error. In that case, consider using the more precise exception to provide the user with additional information.

See also https://tools.ietf.org/html/rfc7231#section-6.5.1.

The 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

中文翻译:
BadRequestHttpException 表示状态码为 400 的“错误请求”HTTP异常。

使用此异常来表示通用的客户端错误。在很多情况下,可能存在一个更准确地描述错误信息的 HTTP 异常。在这种情况下,请考虑提供给用户更准确的错误信息。

参见 https://tools.ietf.org/html/rfc7231#section-6.5.1。

400(错误请求)状态码表示由于明显的客户端错误(例如,格式错误的请求语法,无效的请求消息或欺骗性路由请求),服务器不能或不会处理该请求。

注解:
(1)HTTP 400 Bad Request 响应状态码表示由于语法无效,服务器无法理解该请求。客户端不应该在未经修改的情况下重复此请求。
(2)错误的请求。可能通过用户方面的多种原因引起的,例如在请求体内有无效的 JSON 数据,无效的操作参数,等等。

2、yii\web\ConflictHttpException:状态码 409。

ConflictHttpException represents a “Conflict” HTTP exception with status code 409.

See also https://tools.ietf.org/html/rfc7231#section-6.5.8.

The 409 (Conflict) status code indicates that the request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and esubmit the request. The server SHOULD generate a payload that includes enough information for a user to recognize the source of the conflict.

Conflicts are most likely to occur in response to a PUT request. For example, if versioning were being used and the representation being PUT included changes to a resource that conflict with those made by an earlier (third-party) request, the origin server might use a 409 response to indicate that it can’t complete the request. In this case, the response representation would likely contain information useful for merging the differences based on the revision history.

中文翻译:
ConflictHttpException 表示状态码为 409 的“冲突”HTTP异常。

参见 https://tools.ietf.org/html/rfc7231#section-6.5.8。

409(冲突)状态码表示由于与目标资源的当前状态冲突而无法完成请求。此代码用于用户可能能够解决冲突并提交请求的情况。服务器应该生成一个有效载荷,其中包含足够的信息供用户识别冲突源。

冲突最有可能发生在响应PUT请求时。例如,如果正在使用版本控制并且包含PUT的表示更改为与早期(第三方)请求冲突的资源,则源服务器可能使用409响应来指示它无法完成 请求。在这种情况下,响应表示可能包含对基于修订历史合并差异有用的信息。

注解:
(1)响应状态码 409 Conflict 表示请求与服务器端目标资源的当前状态相冲突。冲突最有可能发生在对 PUT 请求的响应中。例如,当上传文件的版本比服务器上已存在的要旧,从而导致版本冲突的时候,那么就有可能收到状态码为 409 的响应。
(2)表示因为请求存在冲突无法处理该请求,例如多个同步更新之间的编辑冲突。

3、yii\web\ForbiddenHttpException:状态码 403。

ForbiddenHttpException represents a “Forbidden” HTTP exception with status code 403.

Use this exception when a user is not allowed to perform the requested action. Using different credentials might or might not allow performing the requested action. If you do not want to expose authorization information to the user, it is valid to respond with a 404 yii\web\NotFoundHttpException.

See also https://tools.ietf.org/html/rfc7231#section-6.5.3.

The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it. A server that wishes to make public why the request has been forbidden can describe that reason in the response payload (if any).

If authentication credentials were provided in the request, the server considers them insufficient to grant access. The client SHOULD NOT automatically repeat the request with the same credentials. The client MAY repeat the request with new or different credentials. However, a request might be forbidden for reasons unrelated to the credentials.

An origin server that wishes to “hide” the current existence of a forbidden target resource MAY instead respond with a status code of 404 (Not Found).

中文翻译:
ForbiddenHttpException 表示状态码为 403 的“禁止”HTTP异常。

如果用户不被允许执行请求的操作,请使用此异常。使用不同的凭据可能允许或者不允许执行请求的操作。如果您不希望向用户公开授权信息,则可以使用 404 yii\web\NotFoundHttpException 进行响应。

参见 https://tools.ietf.org/html/rfc7231#section-6.5.3。

403(禁止)状态码表示服务器已经理解请求,但是拒绝执行。如果服务器希望公开请求被禁止的原因,可以在响应有效载荷中描述该原因(如果有的话)。

如果请求中提供了身份验证凭据,则服务器认为它们不足以授予访问权限。客户端不应该使用相同的凭据自动重复请求。客户端可以使用新的或不同的凭据重复请求。但是,出于与凭证无关的原因,可能会禁止请求。

如果希望“隐藏”当前存在的禁止目标资源,源服务器可以用状态码 404(未找到)来响应。

注解:
(1)状态码 403 Forbidden 代表客户端错误,指的是服务器端有能力处理该请求,但是拒绝授权访问。这个状态类似于 401,但是进入该状态后,不能再继续进行验证。该访问是永久禁止的,并且与应用逻辑密切相关(例如不正确的密码)。
(2)服务器已经理解请求,但是拒绝执行。与 401 响应不同的是,身份验证并不能提供任何帮助,而且这个请求也不应该被重复提交。如果这不是一个 HEAD 请求,而且服务器希望能够讲清楚为何请求不能被执行,那么就应该在实体内描述拒绝的原因。当然服务器也可以返回一个 404 响应,假如它不希望让客户端获得任何信息。
(3)已经经过身份验证的用户不允许访问指定的 API 末端。

4、yii\web\GoneHttpException:状态码 410。

GoneHttpException represents a “Gone” HTTP exception with status code 410.

Throw a GoneHttpException when a user requests a resource that no longer exists at the requested url. For example, after a record is deleted, future requests for that record should return a 410 GoneHttpException instead of a 404 yii\web\NotFoundHttpException.

See also https://tools.ietf.org/html/rfc7231#section-6.5.9.

The 410 (Gone) status code indicates that access to the target resource is no longer available at the origin server and that this condition is likely to be permanent. If the origin server does not know, or has no facility to determine, whether or not the condition is permanent, the status code 404 (Not Found) ought to be used instead.

The 410 response is primarily intended to assist the task of web maintenance by notifying the recipient that the resource is intentionally unavailable and that the server owners desire that remote links to that resource be removed. Such an event is common for limited-time, promotional services and for resources belonging to individuals no longer associated with the origin server’s site. It is not necessary to mark all permanently unavailable resources as “gone” or to keep the mark for any length of time — that is left to the discretion of the server owner.

A 410 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls (see Section 4.2.2 of [RFC7234]).

中文翻译:
GoneHttpException 表示状态码为 410 的“丢失”HTTP异常。

当用户请求不再存在于请求的 URL 处的资源时,抛出 GoneHttpException。例如,删除记录后,将来对该记录的请求应返回 410 GoneHttpException 而不是 404 yii\web\NotFoundHttpException。

参见 https://tools.ietf.org/html/rfc7231#section-6.5.9。

410(丢失)状态码表示在源服务器上不再可以访问目标资源,并且该条件可能是永久性的。如果源服务器不知道或无法确定条件是否是永久性的,则应该使用状态码 404(未找到)。

410 响应主要用于通过通知接收方资源是故意不可用的以及服务器所有者希望移除到该资源的远程链接来辅助 web 维护的任务。这种事件对于限时,促销服务以及属于不再与源服务器站点相关联的个人的资源是常见的。没有必要将所有永久不可用的资源标记为“已消失”或将标记保留任何时间长度 – 由服务器所有者自行决定。

默认情况下,410 响应可缓存,即,除非方法定义或显式高速缓存控制另有说明(参见[RFC7234]的第4.2.2节)。

注解:
(1)HTTP 410 丢失 说明请求的内容在服务器上不存在了,同时是永久性的不可用。如果不清楚是否为永久或临时的不可用,应该使用 404 ,410 响应默认会被缓存。
(2)表示所请求的资源不再可用,将不再可用。当资源被有意地删除并且资源应被清除时,应该使用这个。在收到 410 状态码后,用户应停止再次请求资源。[39]但大多数服务端不会使用此状态码,而是直接使用 404 状态码。

5、yii\web\MethodNotAllowedHttpException:状态码 405。

MethodNotAllowedHttpException represents a “Method Not Allowed” HTTP exception with status code 405.

See also https://tools.ietf.org/html/rfc7231#section-6.5.5.

The 405 (Method Not Allowed) status code indicates that the method received in the request-line is known by the origin server but not supported by the target resource. The origin server MUST generate an Allow header field in a 405 response containing a list of the target resource’s currently supported methods.

A 405 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls (see Section 4.2.2 of [RFC7234]).

中文翻译:
MethodNotAllowedHttpException 表示状态码为 405 的“方法不允许”HTTP异常。

参见 https://tools.ietf.org/html/rfc7231#section-6.5.5。

405(方法不允许)状态码表示请求行中接收的方法由源服务器知道但目标资源不支持。源服务器必须在 405 响应中生成 Allow 头字段,该字段包含目标资源当前支持的方法的列表。

默认情况下,405 响应可缓存,即,除非方法定义或显式高速缓存控制另有说明(参见[RFC7234]的第4.2.2节)。

注解:
(1)状态码 405 Method Not Allowed 表明服务器禁止了使用当前 HTTP 方法的请求。需要注意的是,GET 与 HEAD 两个方法不得被禁止,当然也不得返回状态码 405。
(2)请求行中指定的请求方法不能被用于请求相应的资源。该响应必须返回一个 Allow 头信息用以表示出当前资源能够接受的请求方法的列表。例如,需要通过 POST 呈现数据的表单上的 GET 请求,或只读资源上的 PUT 请求。
鉴于 PUT ,DELETE 方法会对服务器上的资源进行写操作,因而绝大部分的网页服务器都不支持或者在默认配置下不允许上述请求方法,对于此类请求均会返回 405 错误。
(3)不被允许的方法。请检查 Allow header 允许的 HTTP 方法。

6、yii\web\NotAcceptableHttpException:状态码 406。

NotAcceptableHttpException represents a “Not Acceptable” HTTP exception with status code 406.

Use this exception when the client requests a Content-Type that your application cannot return. Note that, according to the HTTP 1.1 specification, you are not required to respond with this status code in this situation.

See also https://tools.ietf.org/html/rfc7231#section-6.5.6.

The 406 (Not Acceptable) status code indicates that the target resource does not have a current representation that would be acceptable to the user agent, according to the proactive negotiation header fields received in the request (Section 5.3), and the server is unwilling to supply a default representation.

The server SHOULD generate a payload containing a list of available representation characteristics and corresponding resource identifiers from which the user or user agent can choose the one most appropriate. A user agent MAY automatically select the most appropriate choice from that list. However, this specification does not define any standard for such automatic selection, as described in Section 6.4.1.

中文翻译:
NotAcceptableHttpException 表示状态码为 406 的“不接受”HTTP异常。

当客户端请求您的应用程序无法返回的一个 Content-Type 时,请使用此异常。请注意,根据 HTTP 1.1 规范,在这种情况下,您不需要使用此状态码进行响应。

参见 https://tools.ietf.org/html/rfc7231#section-6.5.6。

406(Not Acceptable)状态码表示目标资源没有用户代理可接受的当前表示,根据请求中收到的主动协商头字段(第5.3节),并且服务器不愿意提供默认表示。

服务器应该生成一个有效载荷,其中包含可用的表示特征列表和相应的资源标识符,用户或用户代理可以从中选择最合适的一个。用户代理可以自动从该列表中选择最合适的选项。但是,本规范没有为这种自动选择定义任何标准,如第6.4.1节所述。

注解:
(1)HTTP 协议中的 406 Not Acceptable 状态码表示客户端错误,指代服务器端无法提供与 Accept-Charset 以及 Accept-Language 消息头指定的值相匹配的响应。

在实际应用中,这个错误状态码极少使用:不是给用户返回一个晦涩难懂(且难以更正)的错误状态码,而是将相关的消息头忽略,同时给用户提供一个看得见摸得着的页面。这种做法基于这样一个假设:即便是不能达到用户十分满意,也强于返回错误状态码。

如果服务器返回了这个错误状态码,那么消息体中应该包含所能提供的资源表现形式的列表,允许用户手动进行选择。
(2)参见:内容协商,请求的资源的内容特性无法满足请求头中的条件,因而无法生成响应实体,该请求不可接受。
除非这是一个 HEAD 请求,否则该响应就应当返回一个包含可以让用户或者浏览器从中选择最合适的实体特性以及地址栏表的实体。实体的格式由 Content-Type 头中定义的媒体类型决定。浏览器可以根据格式及自身能力自行作出最佳选择。但是,规范中并没有定义任何作出此类自动选择的标准。

7、yii\web\NotFoundHttpException:状态码 404。

NotFoundHttpException represents a “Not Found” HTTP exception with status code 404.

See also https://tools.ietf.org/html/rfc7231#section-6.5.4.

The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists. A 404 status code does not indicate whether this lack of representation is temporary or permanent; the 410 (Gone) status code is preferred over 404 if the
origin server knows, presumably through some configurable means, that the condition is likely to be permanent.

A 404 response is cacheable by default; i.e., unless otherwise indicated by the method definition or explicit cache controls (see Section 4.2.2 of [RFC7234]).

中文翻译:
NotFoundHttpException 表示状态码为 404 的“未找到”HTTP异常。

参见 https://tools.ietf.org/html/rfc7231#section-6.5.4。

404(未找到)状态码表示源服务器没有找到目标资源的当前表示,或者不愿意透露存在该目标资源。 404 状态码并不表示缺少表示是暂时的还是永久性的,如果是,410(Gone)状态码优先于 404
源服务器可能通过一些可配置的方式知道条件可能是永久性的。

默认情况下,404 响应可缓存,即,除非方法定义或显式高速缓存控制另有说明(参见[RFC7234]的第4.2.2节)。

注解:
(1)状态码 404 Not Found 代表客户端错误,指的是服务器端无法找到所请求的资源。返回该响应的链接通常称为坏链(broken link)或死链(dead link),它们会导向链接出错处理(link rot)页面。

404 状态码并不能说明请求的资源是临时还是永久丢失。如果服务器知道该资源是永久丢失,那么应该返回 410 (Gone) 而不是 404 。
(2)请求失败,请求所希望得到的资源未被在服务器上发现,但允许用户的后续请求。没有信息能够告诉用户这个状况到底是暂时的还是永久的。假如服务器知道情况的话,应当使用 410 状态码来告知旧资源因为某些内部的配置机制问题,已经永久的不可用,而且没有任何可以跳转的地址。404 这个状态码被广泛应用于当服务器不想揭示到底为何请求被拒绝或者没有其他适合的响应可用的情况下。

8、yii\web\ServerErrorHttpException:状态码 500。

ServerErrorHttpException represents an “Internal Server Error” HTTP exception with status code 500.

See also https://tools.ietf.org/html/rfc7231#section-6.6.1.

The 500 (Internal Server Error) status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

中文翻译:
ServerErrorHttpException 表示状态码为 500 的“内部服务器错误”HTTP异常。

参见 https://tools.ietf.org/html/rfc7231#section-6.6.1。

500(内部服务器错误)状态码表示服务器遇到意外情况,导致服务器无法完成请求。

注解:
(1)在 HTTP 协议中,500 Internal Server Error 是表示服务器端错误的响应状态码,意味着所请求的服务器遇到意外的情况并阻止其执行请求。

这个错误代码是一个通用的“全方位”响应代码。通常服务器管理员对于类似于 500 这样的错误会更加详细地记录相关的请求信息来防止以后同样错误的出现。
(2)通用错误消息,服务器遇到了一个未曾预料的状况,导致了它无法完成对请求的处理。没有给出具体错误信息。
(3)内部服务器错误。这可能是由于内部程序错误引起的。

9、yii\web\TooManyRequestsHttpException:状态码 429。

TooManyRequestsHttpException represents a “Too Many Requests” HTTP exception with status code 429.

Use this exception to indicate that a client has made too many requests in a given period of time. For example, you would throw this exception when ‘throttling’ an API user.

See also https://tools.ietf.org/html/rfc6585#section-4.

The 429 status code indicates that the user has sent too many requests in a given amount of time (“rate limiting”).

The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request.

Note that this specification does not define how the origin server identifies the user, nor how it counts requests. For example, an origin server that is limiting request rates can do so based upon counts of requests on a per-resource basis, across the entire server,or even among a set of servers. Likewise, it might identify the user by its authentication credentials, or a stateful cookie.

Responses with the 429 status code MUST NOT be stored by a cache.

中文翻译:
TooManyRequestsHttpException 表示状态码为 429 的“太多请求”HTTP异常。

使用此异常表示客户端在给定的时间段内发出了太多请求。例如,在’限制’API用户时会抛出此异常。

参见 https://tools.ietf.org/html/rfc6585#section-4。

429 状态码表示用户在给定的时间内发送了太多请求(“速率限制”)。

响应表示应该包括解释条件的详细信息,并且可以包括一个 Retry-After 头,指示在发出新请求之前等待多长时间。

请注意,此规范未定义源服务器如何识别用户,也不定义如何计算请求。例如,限制请求率的源服务器可以基于每个资源,整个服务器或甚至一组服务器中的请求计数来这样做。同样,它可以通过其身份验证凭据或有状态 cookie 来标识用户。

429 状态码的响应绝不能由缓存存储。

注解:
(1)在 HTTP 协议中,响应状态码 429 Too Many Requests 表示在一定的时间内用户发送了太多的请求,即超出了“频次限制”。

在响应中,可以提供一个 Retry-After 首部来提示用户需要等待多长时间之后再发送新的请求。
(2)用户在给定的时间内发送了太多的请求。旨在用于网络限速。

10、yii\web\UnauthorizedHttpException:状态码 401。

UnauthorizedHttpException represents an “Unauthorized” HTTP exception with status code 401.

Use this exception to indicate that a client needs to authenticate via WWW-Authenticate header to perform the requested action.

If the client is already authenticated and is simply not allowed to perform the action, consider using a 403 yii\web\ForbiddenHttpException or 404 yii\web\NotFoundHttpException instead.

中文翻译:
UnauthorizedHttpException 表示状态码为 401 的“未认证”HTTP异常。

使用此异常指示客户端需要通过 WWW-Authenticate 头进行身份验证以执行请求的操作。

如果客户端已经过身份验证且根本不允许执行操作,请考虑使用 403 yii\web\ForbiddenHttpException 或 404 yii\web\NotFoundHttpException。

注解:
(1)状态码 401 Unauthorized 代表客户端错误,指的是由于缺乏目标资源要求的身份验证凭证,发送的请求未得到满足。

这个状态码会与 WWW-Authenticate 首部一起发送,其中包含有如何进行验证的信息。

这个状态类似于 403,但是在该情况下,依然可以进行身份验证。
(2)类似于 403 Forbidden,401 语义即“未认证”,即用户没有必要的凭据。该状态码表示当前请求需要用户验证。该响应必须包含一个适用于被请求资源的 WWW-Authenticate 信息头用以询问用户信息。客户端可以重复提交一个包含恰当的 Authorization 头信息的请求。如果当前请求已经包含了 Authorization 证书,那么 401 响应代表着服务器验证已经拒绝了那些证书。如果 401 响应包含了与前一个响应相同的身份验证询问,且浏览器已经至少尝试了一次验证,那么浏览器应当向用户展示响应中包含的实体信息,因为这个实体信息中可能包含了相关诊断信息。
注意:当网站(通常是网站域名)禁止IP地址时,有些网站状态码显示的 401,表示该特定地址被拒绝访问网站。

11、yii\web\UnsupportedMediaTypeHttpException:状态码 415。

UnsupportedMediaTypeHttpException represents an “Unsupported Media Type” HTTP exception with status code 415.

Use this exception when the client sends data in a format that your application does not understand. For example, you would throw this exception if the client POSTs XML data to an action or controller that only accepts JSON.

See also https://tools.ietf.org/html/rfc7231#section-6.5.13.

The 415 (Unsupported Media Type) status code indicates that the origin server is refusing to service the request because the payload is in a format not supported by this method on the target resource. The format problem might be due to the request’s indicated Content-Type or Content-Encoding, or as a result of inspecting the data directly.

中文翻译:
UnsupportedMediaTypeHttpException 表示状态码为 415 的“不支持的媒体类型”HTTP异常。

当客户端应用程序无法理解的格式发送数据时,请使用此异常。例如,如果客户端将 XML 数据 POST 到仅接受 JSON 的操作或控制器,则会抛出此异常。

参见 https://tools.ietf.org/html/rfc7231#section-6.5.13。

415(不支持的媒体类型)状态码表示源服务器拒绝为请求提供服务,因为有效载荷的格式不是此方法在目标资源上支持的格式。 格式问题可能是由于请求指示了 Content-Type 或Content-Encoding,或者是由于直接检查数据。

注解:
(1)415 Unsupported Media Type 是一种 HTTP 协议的错误状态代码,表示服务器由于不支持其有效载荷的格式,从而拒绝接受客户端的请求。

格式问题的出现有可能源于客户端在 Content-Type 或 Content-Encoding 首部中指定的格式,也可能源于直接对负载数据进行检测的结果。
(2)对于当前请求的方法和所请求的资源,请求中提交的互联网媒体类型并不是服务器中所支持的格式,因此请求被拒绝。例如,客户端将图像上传格式为 svg,但服务器要求图像使用上传格式为 jpg。

12、yii\web\RangeNotSatisfiableHttpException:状态码 416。

RangeNotSatisfiableHttpException represents an exception caused by an improper request of the end-user.

This exception thrown when the requested range is not satisfiable: the client asked for a portion of the file (byte serving), but the server cannot supply that portion. For example, if the client asked for a part of the file that lies beyond the end of the file.

Throwing an RangeNotSatisfiableHttpException like in the following example will result in the error page with error 416 to be displayed.

中文翻译:
RangeNotSatisfiableHttpException 表示由最终用户的不正确请求引起的异常。

当请求的范围不可满足时抛出此异常:客户端请求文件的一部分(字节服务),但服务器无法提供该部分。例如,如果客户端要求文件的一部分超出了文件末尾。

抛出 RangeNotSatisfiableHttpException,如下例所示,将导致错误页面显示 416 错误。

注解:
(1)HTTP 416 Range Not Satisfiable 错误状态码意味着服务器无法处理所请求的数据区间。最常见的情况是所请求的数据区间不在文件范围之内,也就是说,Range 首部的值,虽然从语法上来说是没问题的,但是从语义上来说却没有意义。

416 响应报文包含一个 Content-Range 首部,提示无法满足的数据区间(用星号 * 表示),后面紧跟着一个“/”,再后面是当前资源的长度。例如:Content-Range: */12777

遇到这一错误状态码时,浏览器一般有两种策略:要么终止操作(例如,一项中断的下载操作被认为是不可恢复的),要么再次请求整个文件。
(2)简称“Requested Range Not Satisfiable”。客户端已经要求文件的一部分(Byte serving),但服务器不能提供该部分。例如,如果客户端要求文件的一部分超出文件尾端。

13、yii\web\UnprocessableEntityHttpException:状态码 422。

UnprocessableEntityHttpException represents an “Unprocessable Entity” HTTP exception with status code 422.

Use this exception to inform that the server understands the content type of the request entity and the syntax of that request entity is correct but the server was unable to process the contained instructions. For example, to return form validation errors.

中文翻译:
UnprocessableEntityHttpException 表示状态码为 422 的“不可处理的实体”HTTP异常。

使用此异常通知接收方服务器了解请求实体的内容类型,并且该请求实体的语法正确的,但服务器无法处理包含的指令。例如,返回表单验证错误。

注解:
(1)HTTP 422 返回码 表示服务器理解请求实体的内容类型,并且请求实体的语法是正确的,但是服务器不能处理所包含的指令。
(2)请求格式正确,但是由于含有语义错误,无法响应。
(3)数据验证失败 (例如,响应一个 POST 请求)。 请检查响应体内详细的错误消息。

永夜