如何解决 API Gateway 的 5xx 错误？

3 分钟阅读

调用 Amazon API Gateway API 时，出现了 5xx 错误。

概述

HTTP 5xx 响应代码表示服务器出现错误。API Gateway 5xx 错误包括以下情况：

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

解决方法

在开始之前，请按照步骤打开 Amazon CloudWatch Logs 来解决 API Gateway 错误。

使用 CloudWatch 日志查找 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 来调用 Lambda 函数，则可能会收到内部服务器错误。要解决此错误，请参阅我在 API Gateway 中使用阶段变量定义了我的 Lambda 集成。为什么我调用 API 方法时会出现“内部服务器错误”和 500 状态码？

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

HTTP 状态代码映射不正确或缺失时，也有可能导致 500 错误。要解决此问题，请在 API Gateway 中设置模拟集成。

节流问题

如果大量请求限制了后端服务，那么 API Gateway API 可能会返回内部服务器错误。要解决此问题，请激活指数回退和重试机制，然后重试请求。如果问题仍然存在，请检查您的 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 格式返回输出。以 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 Gateway 私有集成。按照说明设置 API Gateway 私有集成。

内部服务故障

如果 AWS 遇到内部服务问题，则您可能会收到 500 错误。等 AWS 或 API Gateway 服务中的问题解决后，使用指数回退策略重试请求。

502 错误：网关错误

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

要解决此问题，请参阅如何通过 Lambda 代理集成解决 API Gateway REST API 中的 HTTP 502 错误？

**注意：**API Gateway 在解释来自后端服务的响应时，会使用映射模板在集成响应部分中映射格式。有关更多信息，请参阅在 API Gateway 中设置集成响应。

503 错误：服务不可用

503 错误代码与后端集成有关；如果 API Gateway API 无法收到响应，也会出现 503 错误代码。

此错误可能发生在以下情况下：

后端服务器超出负荷容量，无法处理新的客户端请求。
后端服务器正在临时维护中。

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

504 错误：端点请求超时

如果集成请求所耗时间超出您的 API Gateway REST API 最大集成超时参数，则 API Gateway 返回 HTTP 504 状态代码。

要解决此错误，请参阅如何解决 API Gateway 的 API HTTP 504 超时错误？