如何使用 API Gateway 对 API HTTP 504 超时错误进行问题排查?

上次更新日期:2022 年 8 月 17 日

当我使用 Amazon API Gateway 调用我的 REST API、HTTP API 或 Websocket API 时,我收到 HTTP 504 错误状态码。如何排查此错误的问题?

简短描述

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

要排查来自 API Gateway 的 504 超时错误,首先在 Amazon CloudWatch 执行日志中确定并验证错误的来源。然后,使用以下一种或多种方法来缩短集成请求的运行时间,直到它们不超时为止。

解决方法

确定并验证 Amazon CloudWatch logs 中 504 错误的来源

1.    对于 Rest APIWebsocket API设置 504 错误的 API Gateway 执行日志记录。对于 HTTP API,激活日志记录以将日志写入 CloudWatch 日志

2.    手动尝试在 API 中重现 504 错误。

3.    在 CloudWatch 控制台中,针对接收错误的集成查看 API Gateway 执行日志

4.    跟踪 CloudWatch 日志中的请求 ID。如果集成有超时,您将看到“Endpoint request body after transformations:(转换后的端点请求正文:)”行之后出现“Execution failed due to a timeout(由于超时,执行失败)”的错误消息。有关更多信息,请参阅如何在我的 CloudWatch 日志中找到 API Gateway REST API 错误?

5.    激活 API 的访问日志记录并使用以下参数变量诊断错误来源:

$context.integration.status:从集成返回的状态码。对于 Lambda 代理集成,这是您的 Lambda 函数代码返回的状态码。
$context.integrationStatus:对于 Lambda 代理集成,此参数表示从 AWS Lambda 而不是后端 Lambda 函数返回的状态码。
$context.integrationLatency:集成延迟(ms)。

有关更多信息,请参阅数据模型、授权方、映射模板和 CloudWatch 访问日志记录的 $context 变量

6.    通过执行以下操作确定错误的来源:

验证是否已调用关联的集成端点。

确认集成完成请求处理所需的时间,并相应地响应 API Gateway。

7.    如果集成未调用,请重试请求。(该错误可能是由于 API Gateway 服务中的临时网络故障造成的。)
注意:确保您的应用程序是幂等的。这可以避免重试 API 请求时的数据冲突。

-或者-

如果集成已调用,但仍返回 504 错误消息,请尝试缩短集成的运行时间。如果是 HTTP API,则可以 尝试增加最大集成请求超时参数

注意:API Gateway REST API 的默认最大集成超时为 29 秒。对于 HTTP API,可以将超时配置为最大值 30 秒。

缩短集成的运行时间

  • 确保您的后端集成仅包含 API Gateway 向客户端发送 HTTP 响应所需的逻辑。考虑将任何非依赖或后处理逻辑移动到其他服务,例如 AWS Lambda
  • 如果网络延迟导致 504 错误,请在客户端应用程序上实施重试逻辑
  • 通过遵循适用于您的平台的优化最佳实践来改善后端集成性能。
  • 考虑设置后端 Lambda 函数的异步调用