如何排查 API Gateway 的 5xx 错误?

上次更新日期:2022 年 9 月 22 日

当我调用 Amazon API Gateway API 时,遇到 5xx 错误。如何排查 API Gateway 5xx 错误?

简短描述

HTTP 5xx 响应代码指示服务器错误。API Gateway 5xx 错误包括:

  • 500 内部服务器
  • 502 无效网关
  • 503 服务不可用
  • 504 端点请求超时

解决方法

开始之前,请按照以下步骤启用 Amazon CloudWatch Logs 以排查 API Gateway 错误

您可以使用 Amazon CloudWatch Logs 查找 API Gateway 中的 5xx 错误。API Gateway 指标 5XXError 指的是给定时间段内捕获的服务器端错误数量。

注意:如果您在运行 AWS 命令行界面(AWS CLI)命令时遇到错误,请确保您使用的是最新版本的 AWS CLI

500 错误:内部服务器错误

此错误可能是由于:

  • AWS Lambda 函数代码中存在错误。
  • 缺少使用阶段变量的权限。
  • HTTP 状态代码映射不正确或缺失。
  • 节流问题。
  • POST 的 HTTP 方法未定义。
  • Lambda 权限。
  • Lambda 函数 JSON 格式问题。
  • 后端负载大小超过 10 MB。
  • 私有端点集成。

Lambda 函数代码中的错误

与 Lambda 集成的 API 端点 500 错误可能指示 Lambda 函数代码中存在错误。有关更多信息和故障排除,请参阅 Amazon API Gateway 和 AWS Lambda 中的错误处理模式

缺少使用阶段变量的权限

如果您设置 API Gateway 以调用使用阶段变量的 AWS Lambda 函数,则可能会收到“internal server error”(内部服务器错误)。要解决此错误,请参阅为什么当我调用 API 方法时收到“internal server error”(内部服务器错误)和 500 状态代码?

HTTP 状态代码映射不正确或缺失

HTTP 状态代码映射不正确或缺少也可能会导致 500 错误。要解决此错误,您可以在 API Gateway 中设置模拟集成

节流问题

如果后端服务因请求数量高而受限,则 API Gateway API 可能会返回“internal server error”(内部服务器错误)。您可以激活指数回退和重试机制,然后重试请求。如果问题仍然存在,请检查 API Gateway 配额限制。如果您超出服务配额限制,则可以请求提高配额

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 授权方基于资源的策略包含 API 调用该函数的权限。按照说明更新 Lambda 函数的基于资源的策略

Lambda 函数 JSON 格式问题

集成的 Lambda 函数不会按照 REST API 和 HTTP API 的预定义 JSON 格式返回输出。更新您的 Lambda 函数或 Lambda 授权方函数 JASON 格式,类似于以下内容:

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 Gateway 私有集成。按照说明设置 API Gateway 私有集成

502 错误:无效网关

502 错误代码与 API Gateway 集成的 AWS 服务相关,例如 AWS Lambda 函数。API Gateway 无法以网关或代理的身份处理响应。

要对与 Lambda 代理函数集成时的 502 错误进行故障排除,请参阅如何解决与 Lambda 代理集成时 API Gateway REST API 中的 HTTP 502 错误?

注意:API Gateway 将会以一种可使用映射模板映射到集成响应部分的格式来解释后端服务中的响应。有关更多信息,请参阅在 API Gateway 中设置集成响应

503 错误:服务不可用

503 错误代码与后端集成相关,并且 API Gateway API 无法接收响应。

如果后端服务出现以下情况,则可能会出现此错误:

  • 超出容量的超负载,并且无法处理新的客户端请求。
  • 后端服务器处于临时维护当中。

要解决此错误,请考虑为后端服务器预置更多资源并在客户端上启用指数回退和重试机制。然后,重试请求。

504 错误:端点请求超时

如果集成请求花费的时间超过 API Gateway REST API 最大集成超时参数,API Gateway 将返回 HTTP 504 状态码。

要解决此错误,请参阅如何使用 API Gateway 对 API HTTP 504 超时错误进行问题排查?


这篇文章对您有帮助吗?


您是否需要账单或技术支持?