如何疑難排解 API 閘道的 5xx 錯誤？

2 分的閱讀內容

當我調用我的 Amazon API Gateway API 時，我收到 5xx 錯誤。

簡短描述

HTTP 5xx 回應代碼表示服務器錯誤。API 閘道 5xx 錯誤包括下列情況：

500 內部伺服器
502 錯誤閘道器
503 服務無法使用
504 端點請求已逾時

解決方法

在開始之前，請按照以下步驟開啟 Amazon CloudWatch 日誌，以對 API 閘道錯誤進行疑難排解。

使用 CloudWatch 日誌，從 API 閘道中找出 5xx 錯誤。API 閘道指標 5XXError 會計算指定期間內擷取的伺服器端錯誤數目。

**注意：**如果您在執行 AWS Command Line Interface (AWS CLI) 命令時收到錯誤，請確定您使用的是最新的 AWS CLI 版本。

500 錯誤：內部服務器錯誤

由於下列任何情況，都可能會發生此錯誤：

AWS Lambda 函數程式碼中的錯誤
缺少使用階段變數的權限
不正確或缺少 HTTP 狀態碼對應
節流問題
未定義的 POST 的 HTTP 方法
Lambda 權限
Lambda 函數 JSON 格式問題
後端承載大小超過 10 MB
私有端點整合
內部服務故障

Lambda 函數程式碼中的錯誤

與 Lambda 整合的 API 端點 500 錯誤可能表示 Lambda 函數在程式碼中存在錯誤。如需詳細資訊和疑難排解，請參閱 Amazon API 閘道和 AWS Lambda 中的錯誤處理模式。

缺少使用階段變數的權限

如果您使用階段變數來設定 API 閘道來叫用 Lambda 函數，則可能會收到內部伺服器錯誤。若要解決此錯誤，請參閱我使用階段變數在 API 閘道中定義了 Lambda 整合。當我叫用 API 方法時，為什麼會收到「內部服務器錯誤」和 500 狀態碼？

不正確或缺少 HTTP 狀態碼對應

不正確或缺少 HTTP 狀態碼對應也會導致 500 錯誤。若要解決此問題，請在 API 閘道中設定模擬整合。

限流問題

如果有大量請求限制後端服務，則 API 閘道 API 可能會傳回內部伺服器錯誤。若要解決此問題，請啟動指數退避並重試機制，然後再試一次請求。如果問題仍然存在，請檢查您的 API 閘道配額限制。如果您超過服務配額限制，則可以要求提高配額。

未定義的 POST 的 HTTP 方法

針對 Lambda 整合，您必須針對整合要求使用 POST 的 HTTP 方法。

執行 AWS CLI 命令 put-integration 以更新方法整合請求：

aws apigateway put-integration \
    --rest-api-id id \
    --resource-id id \
    --http-method ANY \
    --type AWS_PROXY \
    --integration-http-method POST \
    --uri arn:aws:apigateway:us-east-2:lambda:path//2015-03-31/functions/arn:aws:lambda:us-east-2:account_id:function:helloworld/invocations

然後，使用 AWS CLI 命令create-deployment 來部署 REST API：

aws apigateway create-deployment \
    --rest-api-id id \
    --stage-name <value>

Lambda 權限

請確定整合式 Lambda 函數或 Lambda 授權程式的 resource-based 政策包含 API 叫用函數的權限。依照指示更新 Lambda 函數的資源型政策。

Lambda 函數 JSON 格式問題

集成的 Lambda 函數不會根據 REST API 和 HTTP API 的預定義 JSON 格式傳回輸出。以 JSON 格式更新您的 Lambda 函數或 Lambda 授權程式：

REST API：

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": "..."
}

HTTP API：

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
    "body": "..."
}

後端承載大小超過 10 MB

後端承載大小上限為 10 MB。您無法增加大小。確保後端承載大小未超過 10 MB 的預設配額。

私有端點整合

如果您使用私有 API 端點，則還必須設定 API 閘道私有整合。依照指示設定 API 閘道私有整合。

內部服務故障

如果 AWS 遇到內部服務問題，您可能會收到 500 錯誤。等待問題在 AWS 或 API 閘道服務中解決，然後使用指數退避重試請求。

502 錯誤：錯誤閘道

502 錯誤碼與您的 API 閘道整合的 AWS 服務有關，例如 AWS Lambda 函數。API 閘道無法以閘道或代理的形式處理回應。

若要疑難排解此問題，請參閱如何透過 Lambda 代理整合來解決 API 閘道 REST API 中的 HTTP 502 錯誤？

**注意：**當 API Gateway 解譯來自後端服務的回應時，它會使用對應範本來對應整合回應區段中的格式。如需詳細資訊，請參閱在 API 閘道中設定整合回應。

503 錯誤：服務無法使用

503 錯誤碼與後端整合相關，且 API 閘道 API 無法收到回應。

在下列情況下，可能會發生這個錯誤：

後端伺服器超出容量，無法處理新的用戶端要求。
後端伺服器正在暫時性維護中。

若要解決此錯誤，請考慮為後端伺服器佈建更多資源，並在用戶端上啟動指數退避和重試機制。然後，再試一次請求。

504 錯誤：端點請求逾時

如果整合要求花費的時間超過您的 API 閘道 REST API 最大整合逾時參數，則 API 閘道會傳回 HTTP 504 狀態碼。

若要解決此錯誤，請參閱如何使用 API 閘道疑難排解 API HTTP 504 逾時錯誤？