当我使用 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 日志中 504 错误的来源
1. 对于 Rest API 和 Websocket API,为 504 错误设置 API Gateway 执行日志。对于 HTTP API,激活日志记录以将日志写入 CloudWatch 日志。
2. 手动尝试在 API 中重现 504 错误。
3. 激活 API 的访问日志记录,然后使用以下参数变量来诊断错误来源:
$context.integration.status: The status code returned from an integration. For AWS Lambda proxy integrations, this is the status code that your Lambda function code returns.
$context.integrationStatus: For Lambda proxy integration, this parameter represents the status code returned from Lambda, not from the backend Lambda function.
$context.integrationLatency: The integration latency in ms.
有关更多信息,请参阅数据模型、授权方、映射模板和 CloudWatch 访问日志记录的 $context 变量。
4. 使用以下 CloudWatch Log Insights 查询从访问日志中筛选“5XX”状态码:
fields @timestamp, @message, @logStream
| filter status like ‘5’
| sort @timestamp desc
| display @timestamp,httpMethod,resourcePath,status,extendedRequestId,requestId
5. 在 CloudWatch 控制台中,查看接收错误的集成的 API Gateway 执行日志。
6. 在 CloudWatch 日志中追踪请求 ID。如果集成出现超时,则您会在“转换后的端点请求正文:”行后看到“因超时而导致执行失败”错误。有关更多信息,请参阅如何在我的 CloudWatch 日志中找到 API Gateway REST API 错误?
7. 使用以下 CloudWatch Log Insights 查询筛选错误并选择您的 API Gateway 执行日志组:
fields @timestamp, @message
|filter @message like "Execution failed due to a timeout error"
|sort @timestamp desc
8. 要确定错误来源,请验证是否已调用关联的集成端点。
9. 确认集成花了多长时间才完成请求的处理并响应 API Gateway。
10. 如果未调用集成,则在客户端上实施 API 重试。(该错误可能是由 API Gateway 服务中的临时网络故障引起的。)
请注意:确保您的应用程序是幂等的。这样可以避免在您重试 API 请求时出现数据冲突。
-或-
如果调用了集成但仍返回 504 错误消息,请尝试缩短集成的运行时系统。如果是 HTTP API,则可以尝试增加最大集成请求超时参数。
**请注意:**API Gateway REST API 的默认最大集成超时时间为 29 秒。对于 HTTP API,可以将超时配置为最大值 30 秒。无法提高最大值限制。
减少集成的运行时系统
- 确保您的后端集成仅包含 API Gateway 向客户端发送 HTTP 响应所需的逻辑。考虑将任何非依赖逻辑或后处理逻辑移至其他服务,例如 Lambda。
- 如果网络延迟导致 504 错误,请在客户端应用程序上实施重试逻辑。
- 遵循平台的优化最佳实践,提高后端集成性能。
- 考虑设置后端 Lambda 函数的异步调用。
相关信息
设置 REST API 集成
在 API Gateway 中设置 WebSocket API 集成请求
为 HTTP API 配置集成
Amazon API Gateway 配额和重要注意事项