如何让AWS API Gateway与Lambda调用返回413 Payload Too Large？

我之前也遇到过这个问题，确实挺头疼的——默认的502响应对客户端太不友好了。问题根源在于：Lambda同步调用的payload上限是6MB，当请求超过这个大小，API Gateway无法成功转发请求到Lambda，就会返回502 Bad Gateway。下面是几个可行的解决方法，你可以根据自己的API类型（REST/HTTP）选择合适的方案：

方法1：自定义网关响应，将502映射为413 #

这是最直接的方案，不需要修改业务代码，直接通过API Gateway配置把默认的502错误转换成413：

• 登录AWS控制台，进入你的API Gateway实例（以REST API为例）。
• 左侧菜单找到Gateway Responses，找到对应BAD_GATEWAY（或INTEGRATION_ERROR）的响应条目。
• 编辑该响应：
  • 将HTTP Status修改为413。
  • 在Response Body Templates中添加对应Content-Type（比如application/json）的模板，示例：

    {
      "error": "Payload Too Large",
      "message": "请求体大小超过最大允许的6MB限制"
    }
    

• 保存后重新部署API，之后遇到大payload导致的502就会自动返回413。

方法2：提前拦截大请求，避免调用Lambda #

这种方法更高效，在请求到达Lambda之前就直接返回413，节省资源。

方式A：用Lambda授权器检查请求大小 #

创建一个轻量的Lambda授权器，在授权逻辑里判断请求大小，超过阈值就返回413：

1. 创建一个Lambda函数，示例Python代码：

   import json
   
   def lambda_handler(event, context):
       # 获取请求总大小（字节）
       request_size = int(event['requestContext']['requestSize'])
       max_allowed = 6 * 1024 * 1024  # 6MB
   
       if request_size > max_allowed:
           return {
               "principalId": "blocked",
               "policyDocument": {
                   "Version": "2012-10-17",
                   "Statement": [{
                       "Action": "execute-api:Invoke",
                       "Effect": "Deny",
                       "Resource": event['methodArn']
                   }]
               },
               "statusCode": 413,
               "context": {"error": "Payload Too Large"}
           }
   
       # 正常请求的授权逻辑（如果不需要授权可以直接返回允许）
       return {
           "principalId": "allowed",
           "policyDocument": {
               "Version": "2012-10-17",
               "Statement": [{
                   "Action": "execute-api:Invoke",
                   "Effect": "Allow",
                   "Resource": event['methodArn']
               }]
           }
       }
   

2. 在API Gateway的POST方法中配置这个Lambda授权器。
3. 回到Gateway Responses，找到ACCESS_DENIED条目，将其HTTP状态码改为413，并设置对应的响应体，这样授权器拒绝时就会返回413。

方式B：用映射模板拦截（仅REST API） #

在POST方法的Integration Request中添加映射模板，通过Velocity模板语言判断请求大小：

• 选择对应Content-Type（比如application/json）的映射模板，输入以下内容：

  #if($context.requestSize > 6291456)
      #set($context.responseOverride.status = 413)
      #set($context.responseOverride.body = '{"error": "Payload Too Large", "message": "最大允许大小为6MB"}')
  #else
      $input.json('$')
  #end
  

• 保存后部署API，超过大小的请求会直接返回413，不会触发Lambda。

方法3：HTTP API的适配方案 #

如果你使用的是HTTP API，步骤略有不同：

• 在路由的Integration设置中，配置Lambda授权器检查请求大小（逻辑同方法2A）。
• 在Gateway Responses中找到502 Bad Gateway，将其HTTP状态码改为413，并自定义响应体。

额外建议：处理超大文件的最佳实践 #

如果需要处理远大于6MB的文件，建议使用S3预签名URL方案：

1. 客户端先调用你的API获取S3预签名URL。
2. 客户端直接将文件上传到S3，绕过API Gateway和Lambda的payload限制。
3. S3上传完成后触发Lambda处理文件（通过S3事件通知）。

这种方式不仅能解决大小限制问题，还能提升上传效率，减少API Gateway和Lambda的压力。

内容的提问来源于stack exchange，提问作者Bram Vandewalle