網關響應指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變量）。

操作步驟

步驟 1 進入API網關控制臺頁面。

步驟 2 根據實際業務在左側導航欄上方選擇實例。

步驟 3 在左側導航欄選擇“API管理 > API分組”。

步驟 4 單擊 分組名稱 。

步驟 5 單擊“分組信息”頁簽。

步驟 6 在“網關響應”區域，您可以新增或編輯網關響應。

如果修改完默認網關響應后，需要恢復默認配置，單擊“恢復默認配置”即可。

網關錯誤響應類型說明

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
當前網關錯誤響應的錯誤類型