當我在 API Gateway REST API 中使用 VPC 連結整合時，要如何對 500 錯誤進行疑難排解？

簡短說明

API Gateway 搭配 VPC 連結整合時，可能無法將流量轉送至後端資源。

由於以下其中一個原因，也可能會傳回「HTTP 500」狀態碼：

• VPC 連結處於失敗狀態。或是端點服務不存在，或處於已拒絕狀態。
• 目標群組顯示已註冊的目標為運作狀態不良或未使用。
• 安全群組未允許特定連接埠的流量。
• 網路存取控制清單 (網路 ACL) 封鎖流量。
• 目標未在目標連接埠上接聽。
• 網域名稱憑證與啟用 TLS 的 Network Load Balancer 或 Application Load Balancer 不相符。

如果您為 API 啟用 Amazon CloudWatch Logs，則執行日誌中會顯示包含錯誤原因的錯誤訊息。

解決方法

驗證後端連線能力

在您對 API Gateway 進行疑難排解前，請採取以下其中一個動作：

• 使用 curl 或 Postman 等工具，從 VPC 內向 Network Load Balancer DNS 名稱傳送請求。如果請求失敗，則表示 Network Load Balancer 組態、後端目標運作狀態或網路設定存在問題。
• 使用 VPC Reachability Analyzer 驗證從 API Gateway VPC 連結子網路到後端資源的流量路徑。

確認錯誤原因

啟用 CloudWatch API 記錄。同時設定執行記錄。

**注意：**當您設定記錄設定時，請將日誌層級設為 Error and info logs (錯誤和資訊日誌)，並選取 Data tracing (資料追蹤)。這些設定可為您提供完整的請求和回應日誌。

若要識別錯誤原因，請檢閱 CloudWatch 中 REST API 的執行日誌。接著，根據您收到的錯誤訊息進行疑難排解。

疑難排解「There was an internal error while executing your request」

您收到以下錯誤訊息：

「Error: Execution failed due to configuration error: There was an internal error while executing your request」

若要解決此問題，請檢查以下組態：

• VPC 連結負載平衡器存在，且未遭刪除。
• VPC 連結處於可用狀態。如果 VPC 連結處於失敗狀態，則您必須建立新的 VPC 連結，並將該連結與您的 API 建立關聯。
  **注意：**在您修改整合請求後，請部署 API。
• 與目標 Network Load Balancer 關聯的 VPC 連結端點連線處於可用狀態。
• 您已在 Allow principals (允許主體) 中列出 AWS 區域專屬 API Gateway 帳戶 ID。
• 端點服務的 Endpoint connections (端點連線) 中，來自 API Gateway 帳戶的端點連線處於可用狀態。
• 如果 API Gateway 使用階段變數參考 VPC ID，則請確認 VPC 連結 ID 正確。
• VPC 連結負載平衡器會在您為請求設定的 HTTP/HTTPS 連接埠上接聽。請確定您已為正確的連接埠設定接聽程式，且網路 ACL 未封鎖請求。
• 目標群組接受請求。網路 ACL 必須允許傳入和傳出流量，且安全群組必須允許已設定連接埠的傳入流量。
• 如果請求傳回「HTTP 500」狀態碼錯誤，則連線可能會收到 TCP 重設 (RST) 封包的總數。後端伺服器必須正在執行。此外，目標連接埠上的後端目標必須有服務正在執行。請驗證後端目標在目標連接埠上接聽。
• 您已停用 AWS PrivateLink 流量的傳入規則。Enforce inbound rules on PrivateLink traffic (對 PrivateLink 流量強制套用傳入規則) 選項會將所有傳入和傳出安全群組規則套用至來自 VPC 連結的流量。如果您未設定安全群組以允許來自 VPC 連結的流量，則安全群組可能會封鎖 API Gateway 流量。

疑難排解「Host name 'domain.com.com' does not match the certificate subject provided by the peer」

您收到以下錯誤訊息：

「Error: Execution failed due to configuration error: Host name 'domain.com.com' does not match the certificate subject provided by the peer (CN=myinstance.com)」

請確定端點網域名稱與啟用 TLS 的負載平衡器目標所傳回的憑證相符。支援的憑證認證機構提供者清單必須信任您在目標執行個體上設定的憑證。

疑難排解「PKIX path building failed:...unable to find valid certification path to requested target」

您收到以下錯誤訊息：

「Error: Execution failed due to configuration error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target」

當 REST API 服務將整合所傳回的憑證標示為無效時，就會發生此錯誤。即使您在整合的 TlsConfig 屬性上將 insecureSkipVerification 設為 true，API Gateway 仍會執行基本的憑證驗證。

API Gateway 會檢視以下資訊：

• 憑證到期日
• 主機名稱
• 是否存在根憑證認證機構 (CA)
  **注意：**整合必須包含並傳回完整的憑證鏈，API Gateway 才能驗證信任鏈並建立安全連線。完整鏈包含從伺服器憑證到根 CA 憑證之間的所有中繼憑證。此外，根 CA 必須包含 keyUsage 且設定為 keyCertSign，以及 basicConstraints 並設定為 CA:TRUE。如需詳細資訊，請參閱 x-amazon-apigateway-integration.tlsConfig 物件。

疑難排解「Cannot verify ECDH ServerKeyExchange signature」

您收到以下錯誤訊息：

「Error: Execution failed due to configuration error: Cannot verify ECDH ServerKeyExchange signature」

當金鑰與對應的憑證不相符，且 TLS 交握失敗時，就會發生此錯誤。若要解決此問題，請檢查您用於設定 CA、憑證與金鑰的檔案內容。

疑難排解「Execution failed due to an internal error」

您收到以下錯誤訊息：

「Error: Execution failed due to an internal error」

當 API Gateway 因為目標在負載平衡器上重設，而無法透過 VPC 連結連線至負載平衡器時，就會發生此錯誤。若要解決此問題，請將目標的逾時時間設定得比負載平衡器的預設逾時時間 (350 秒) 更長。

疑難排解「Execution failed due to a VPC link error」

您收到以下錯誤訊息：

「Error: Execution failed due to a VPC link error」

API Gateway 具有許多相依項目。當其中一個相依項目發生暫時性連線失敗時，您可能會看到錯誤。對於低頻率錯誤，最佳實務是實作採用指數退避的重試。如果錯誤頻率很高，請聯絡 AWS Support。請確定您提供顯示錯誤的 API Gateway 執行日誌。

疑難排解「Execution failed due to configuration error: Not a valid protocol version」

您收到以下錯誤訊息：

「Error: Execution failed due to configuration error: Not a valid protocol version」

當整合傳回的 HTTP 回應無效且未遵循 HTTP 規格時，就會發生此錯誤。整合的後端可能會將無效的資料傳回給 API Gateway。

若要疑難排解此問題，請採取以下動作：

• 重現您從 API Gateway 發出的請求。若要測試 API Gateway 使用的服務端點，請建立連結至服務端點 ID 的 VPC 端點。您也可以執行封包擷取，以檢閱整合後端所傳回的回應。
• 為避免重複加密，請根據目標的回應，將負載平衡器通訊協定變更為 TLS 或 TCP。
• 請確定在整合的 TlsConfig 屬性上，已將 insecureSkipVerification 設為 true。

監控並偵測錯誤與問題

請使用以下工具來判斷問題屬於暫時性，還是存在持續性的組態問題：

• 在 CloudWatch 中監控 5XXError 與 IntegrationLatency API Gateway 指標，以偵測模式。
• 啟用 AWS X-Ray 追蹤，以監控從 API Gateway 到 VPC 連結、從 VPC 連結到 Network Load Balancer，以及從 Network Load Balancer 到後端的請求路徑。

相關資訊

了解 Amazon API Gateway 私有整合中的 VPC 連結

使用 Amazon CloudWatch 指標監控 REST API 執行

為 API Gateway 私有整合設定 Network Load Balancer