自定义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网关运行时可获取变量。
操作步骤
- 进入API网关控制台页面。
- 根据实际业务在左侧导航栏上方选择实例。
- 在左侧导航栏选择“API管理 > API分组”。
- 单击分组名称。
- 单击“分组信息”页签。
- 在“网关响应”区域，您可以新增或编辑网关响应。
如果修改完默认网关响应后，需要恢复默认配置，单击“恢复默认配置”即可。
网关错误响应类型说明
API网关提供的错误响应类型见下表，其中响应状态码可以按实际需要做自定义修改。
|
错误说明 |
默认的响应状态码 |
详细说明 |
|---|---|---|
|
拒绝访问 |
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 |
API网关运行时可获取变量
|
运行时变量名称 |
描述 |
|---|---|
|
$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 |
当前网关错误响应的错误类型 |
