# 自定义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个网关响应。
- 最多支持10个响应头自定义，响应头的key支持数字、英文字母和下划线（1到128位），value可以引用运行时变量（可以引用的变量见[API网关运行时可获取变量]），value不能包含"\[\["和"\]\]"。
- 不论是默认网关响应"default"或是您自定义的网关响应，响应类型范围固定不可修改。您可以修改每种响应的状态码，以及响应内容。
- 网关响应所定义的错误类型固定且不可修改，具体见[网关错误响应类型说明]。
- 响应内容支持调用API网关运行时变量（$context变量），具体见[API网关运行时可获取变量]。
 
#### 自定义网关响应
1. 进入[API网关控制台](https://console.huaweicloud.com/apig2/#/overview)页面。

2. 根据实际业务在左侧导航栏上方选择实例。

3. 在左侧导航栏选择"API管理 \> API分组"。

4. 单击分组名称，进入"分组信息"页面。
5. 在"网关响应"区域，您可以新增或编辑网关响应。 
   如果修改完默认网关响应后，需要恢复默认配置，单击"恢复默认配置"即可。
   
   
 
 #### 网关错误响应类型说明
API网关提供的错误响应类型见下表，其中响应状态码可以按实际需要做自定义修改。
表1API网关的错误响应类型 
| 错误说明             | 默认的响应状态码 | 详细说明                                        |
|:---|:---|:---|
| 拒绝访问             | 403      | 拒绝访问，如触发配置的访问控制策略、或异常攻击检测拦截                 |
| 自定义认证配置错误        | 500      | 自定义认证方异常，通信失败、返回异常响应等错误                     |
| 自定义认证失败          | 500      | 自定义认证方返回认证失败                                |
| 自定义认证身份来源错误      | 401      | 前端自定义认证的身份来源信息缺失或不合法错误                      |
| 第三方认证配置错误        | 500      | 第三方认证方异常，通信失败、返回异常响应等错误                     |
| 第三方认证失败          | 401      | 第三方认证方返回认证失败                                |
| 第三方认证身份来源错误      | 401      | 第三方认证的身份来源信息缺失                              |
| 认证失败             | 401      | 认证失败，IAM或APP认证校验失败                          |
| 认证身份来源缺失         | 401      | 认证身份来源信息缺失                                  |
| 后端超时             | 504      | 后端超时，与后端的网络交互超过预配置的时间错误                     |
| 后端不可用            | 502      | 后端不可用，网络不可达错误                               |
| 默认4XX            | -        | 其它4XX类错误                                    |
| 默认5XX            | -        | 其它5XX类错误                                    |
| 未找到匹配的API        | 404      | 未匹配到API                                     |
| 请求参数错误           | 400      | 请求参数校验失败、不支持的HTTP方法                         |
| 调用次数超出阈值         | 429      | API调用次数超出所配置的流量策略阈值                         |
| 凭据未授权            | 401      | 使用的凭据未被授权访问该API                             |
| 未获取到待编排的参数       | 400      | 参数编排时，没有从请求中获取到待编排的参数                       |
| 参数编排失败           | 400      | 参数编排时，没有匹配上任何编排规则                           |
| OIDC认证校验token失败  | 401      | 使用校验token方式进行OIDC认证时，token校验失败              |
| OIDC认证获取IDP信息失败  | 400      | OIDC认证时IDP服务不可用或者网络不可达，无法从配置的discovery处获取信息 |
| OIDC认证授权码流程失败    | 401      | 使用浏览器进行OIDC认证时，授权码流程处理失败                    |
| JWT认证插件校验token失败 | 401      | JWT认证插件校验Token失败                            |
   
 #### API网关运行时可获取变量
表2网关错误响应消息体支持的变量 
| 运行时变量名称                               | 描述                             |
|:---|:---|
| $context.apiId                        | API的ID                         |
| $context.apiName                      | API名称                          |
| $context.appId                        | API调用者的凭据对象ID                  |
| $context.appName                      | API调用者的凭据对象名称                  |
| $context.requestId                    | 当次API调用生成请求ID                  |
| $context.stage                        | API调用的部署环境                     |
| $context.sourceIp                     | API调用者的源地址                     |
| $context.reqPath                      | API请求路径，不包含query参数             |
| $context.reqUri                       | API请求路径，包含query参数              |
| $context.reqMethod                    | API请求方法                        |
| $context.authorizer.frontend.property | 前端自定义认证响应的context映射的指定键值对的字符串值 |
| $context.authorizer.backend.property  | 后端自定义认证响应的context映射的指定键值对的字符串值 |
| $context.error.message                | 当前网关错误响应的错误信息                  |
| $context.error.code                   | 当前网关错误响应的错误码                   |
| $context.error.type                   | 当前网关错误响应的错误类型                  |