HTTP 响应行 错误类型响应码

新增网关响应(知识补充，和文章内容无关)

---

网关响应	网关响应指未能成功处理API请求，从而产生的错误响应。 API网关提供默认的网关响应（default）。如果您需要自定义响应状态码或网关响应内容，可在API分组中新增网关响应，按照您自己的响应内容，符合JSON格式即可。

新增网关响应_API网关 APIG_用户指南_API管理_华为云

网关响应指API网关未能成功处理API请求，从而产生的错误响应。API网关提供默认的网关响应（default），如果您需要自定义响应状态码或网关响应内容，可在API分组管理中新增网关响应，其中响应内容符合JSON格式即可。

 例如，“default”网关的响应内容为：

{"error_code": "$context.error.code", "error_msg": "$context.error.message", "request_id": "$context.requestId"}

您可以自定义为：

{"errorcode": "$context.error.code", "errormsg": "$context.error.message", "requestid": "$context.requestId","apiId":"$context.apiId"}

JSON体的内容可以按需定制，包括增减字段内容。

说明：

• 每个分组最多可新增4个网关响应。
• 不论是默认网关响应“default”或是您自定义的网关响应，响应类型范围固定不可修改。您可以修改每种响应的状态码，以及响应内容。
• 网关响应所定义的错误类型固定且不可修改，具体见网关错误响应类型说明。
• 响应内容支持调用API网关运行时变量（$context变量），具体见API网关运行时可获取变量。

API网关运行时可获取变量

表2 网关错误响应消息体支持的变量

运行时变量名称	描述
$context.apiId	API的ID
$context.appId	API调用者的凭据对象ID
$context.requestId	当次API调用生成请求ID
$context.stage	API调用的部署环境
$context.sourceIp	API调用者的源地址
$context.authorizer.frontend.property	前端自定义认证响应的context映射的指定键值对的字符串值
$context.authorizer.backend.property	后端自定义认证响应的context映射的指定键值对的字符串值
$context.error.message	当前网关错误响应的错误信息
$context.error.code	当前网关错误响应的错误码
$context.error.type	当前网关错误响应的错误类型

网关错误响应类型说明(知识补充，和文章内容无关)

---

API网关提供的错误响应类型见下表，其中响应状态码可以按实际需要做自定义修改。

表1 API网关的错误响应类型

错误说明	默认的响应状态码	详细说明
拒绝访问	403	拒绝访问，如触发配置的访问控制策略、或异常攻击检测拦截
自定义认证配置错误	500	自定义认证方异常，通信失败、返回异常响应等错误
自定义认证失败	500	自定义认证方返回认证失败
自定义认证身份来源错误	401	前端自定义认证的身份来源信息缺失或不合法错误
认证失败	401	认证失败，IAM或APP认证校验失败
认证身份来源缺失	401	认证身份来源信息缺失
后端超时	504	后端超时，与后端的网络交互超过预配置的时间错误
后端不可用	502	后端不可用，网络不可达错误
默认4XX	-	其它4XX类错误
默认5XX	-	其它5XX类错误
未找到匹配的API	404	未匹配到API
请求参数错误	400	请求参数校验失败、不支持的HTTP方法
调用次数超出阈值	429	API调用次数超出所配置的流量策略阈值
凭据未授权	401	使用的凭据未被授权访问该API

API网关运行时可获取变量

表2 网关错误响应消息体支持的变量

运行时变量名称	描述
$context.apiId	API的ID
$context.appId	API调用者的凭据对象ID
$context.requestId	当次API调用生成请求ID
$context.stage	API调用的部署环境
$context.sourceIp	API调用者的源地址
$context.authorizer.frontend.property	前端自定义认证响应的context映射的指定键值对的字符串值
$context.authorizer.backend.property	后端自定义认证响应的context映射的指定键值对的字符串值
$context.error.message	当前网关错误响应的错误信息
$context.error.code	当前网关错误响应的错误码
$context.error.type	当前网关错误响应的错误类型

HTTP常见的错误码

---

4xx：客户端发生了错误

• 常见的是资源找不到了（404）
• 资源请求需要认证认证失败（401）（有些时候需要登入，那么就要传入认证信息，认证信息也就是账号和密码，出现401说明认证有问题，说明账号密码有问题）
• 认证成功但是权限不够（403）

5xx： 服务端发生了错误（客户端请求的参数都是正确的，但是服务端在解析处理的时候发生了错误）

• 网关超时（504）
• 内部错误（500）
• 网关错误（502）
• 服务不可用（503）

400 500响应码，搞清楚这些响应码，搞清楚其含义，对于我们快速的定位问题非常有帮助。

响应码分类： 4xx（一）

---

• 4xx：客户端出现错误

• 400 Bad Request：服务器认为客户端出现了错误，但不能明确判断为以下哪种错误时使用此错误码。例如HTTP请求格式错误。（请求不合法）

 

• 401 Unauthorized：用户认证信息缺失或者不正确，导致服务器无法处理请求。

• 407 Proxy Authentication Required：对需要经由代理的请求，认证信息未通过代理

服务器的验证

• 403 Forbidden：服务器理解请求的含义，但没有权限执行此请求（对于服务器下面某个目录里面的文件访问可能没有权限，这个时候客户端就会收到forbidden）

• 404 Not Found：服务器没有找到对应的资源

• 410 Gone：服务器没有找到对应的资源，且明确的知道该位置永久性找不到该资源

响应码分类： 4xx（二）

---

• 405 Method Not Allowed：服务器不支持请求行中的 method 方法

• 406 Not Acceptable：对客户端指定的资源表述不存在（例如对语言或者编码有要

求），服务器返回表述列表供客户端选择。

• 408 Request Timeout：服务器接收请求超时

• 409 Conflict：资源冲突，例如上传文件时目标位置已经存在版本更新的资源

• 411 Length Required：如果请求含有包体且未携带 Content-Length 头部，且不属于chunk类请求时，返回 411

响应码分类： 4xx（三）

---

• 412 Precondition Failed：复用缓存时传递的 If-Unmodified-Since 或 If-

None-Match 头部不被满足

• 413 Payload Too Large/Request Entity Too Large：请求的包体超出服务器能处理的最大长度(在使用wordpress搭建博客的话，默认上传的附件只有2m，就是wordpress的插件，我们通常需要将默认的2M向上去调整，就不会得到413这样的错误了)

• 414 URI Too Long：请求的 URI 超出服务器能接受的最大长度

• 415 Unsupported Media Type：上传的文件类型不被服务器支持（比如wordpress站点拒绝exe可执行文件上传，防止有安全的风险）

• 416 Range Not Satisfiable：无法提供 Range 请求中指定的那段包体

• 417 Expectation Failed：对于 Expect 请求头部期待的情况无法满足时的

响应码

响应码分类： 4xx（四）

---

• 421 Misdirected Request：服务器认为这个请求不该发给它，因为它没有能力

处理。

• 426 Upgrade Required：服务器拒绝基于当前 HTTP 协议提供服务，通过

Upgrade 头部告知客户端必须升级协议才能继续处理。

• 428 Precondition Required：用户请求中缺失了条件类头部，例如 If-Match

• 429 Too Many Requests：客户端发送请求的速率过快

调用次数超出阈值

429

API调用次数超出所配置的流量策略阈值

• 431 Request Header Fields Too Large：请求的 HEADER 头部大小超过限制

• 451 Unavailable For Legal Reasons：RFC7725 ，由于法律原因资源不可访问

响应码分类： 5xx（一）

---

• 5xx：服务器端出现错误

• 500 Internal Server Error：服务器内部错误，且不属于以下错误类型

• 501 Not Implemented：服务器不支持实现请求所需要的功能（当前请求的功能还没有去实现，需要服务器去升级或者添加相应的功能）

• 502 Bad Gateway：代理服务器无法获取到合法响应（在源服务器之间有代理服务器，但是代理服务器连接不到源服务器，或者说代理服务没有办法从源服务器中获取到合法的响应）

• 503 Service Unavailable：服务器资源尚未准备好处理当前请求（比如服务端做请求的限速，或者对用户的IP做并发连接的限制，当达到上限的时候，都有可能发送503）

响应码分类： 5xx（二）

---

• 504 Gateway Timeout：代理服务器无法及时的从上游获得响应（表示代理服务器和源服务器之间出现了超时，比如上传巨大的文件或者下载巨大的文件，但是我们代理服务器类似于nginx，它配置的超时时间是一分钟，一分钟之内源服务器还没有及时的响应它，那么代理服务器就会给客户端发送504，所以返回504表示代理服务器设置的超时时间可能过小）

• 505 HTTP Version Not Supported：请求使用的 HTTP 协议版本不支持

• 507 Insufficient Storage：服务器没有足够的空间处理请求

• 508 Loop Detected：访问资源时检测到循环

• 511 Network Authentication Required：代理服务器发现客户端需要进行身份验证才能获得网络访问权限