Hey Ryan, let's break down that 504 timeout issue you're hitting—since you’ve confirmed your Lambda works perfectly on its own, the problem’s definitely in the API Gateway setup or the handoff between API Gateway and Lambda. Here’s where to start troubleshooting:

API Gateway has a default integration timeout of 29 seconds, but this is often the culprit if your Lambda runs close to that window (or occasionally exceeds it):

• Head to your API Gateway console, navigate to the integration request for your endpoint, and verify the timeout setting. If your Lambda needs a bit more breathing room (just make sure it’s under Lambda’s max 15-minute limit), adjust this value upward.
• Double-check that your Lambda’s execution timeout is set to be less than or equal to API Gateway’s integration timeout. For example, if Lambda is set to 30 seconds and API Gateway is at 29, you’ll hit a timeout every time.

If you’re using Lambda proxy integration (the most common setup), API Gateway expects a very specific response structure from Lambda. If this is malformed, API Gateway can get stuck processing it, leading to timeouts:
Your Lambda must return something like this:

{
  "statusCode": 200,
  "headers": {
    "Content-Type": "application/json",
    "Access-Control-Allow-Origin": "https://your-frontend-domain.com" // Match your actual frontend URL
  },
  "body": JSON.stringify(yourDynamoDBResults)
}

• Missing statusCode, passing a non-string body, or incorrect CORS headers can all cause silent failures that manifest as timeouts.

Even with valid Cognito auth, misconfigured CORS can lead to weird timeout-like behavior (especially if the preflight OPTIONS request fails):

• Ensure your API Gateway’s CORS settings explicitly allow your frontend domain, and include the Authorization header (since you’re using Cognito tokens).
• Verify the OPTIONS method is properly configured—sometimes manual CORS setups skip adding the correct response headers for OPTIONS requests, which blocks the actual data request.

Just because your Lambda works when tested directly doesn’t mean API Gateway has permission to invoke it:

• Go to the IAM console, find the execution role attached to your API Gateway, and check its permission policies. Make sure there’s a statement allowing lambda:InvokeFunction for your specific Lambda ARN.
• If your Lambda is in a VPC, ensure API Gateway can reach it: either use a VPC Link for API Gateway, or confirm your Lambda isn’t locked in a VPC that API Gateway can’t access.

Lambda logs will tell you if it ran, but API Gateway logs will show you what’s happening before and after the Lambda call:

• Enable CloudWatch Logs for your API Gateway (under the "Logs/Tracing" tab in the console) and set the log level to INFO or DEBUG.
• Look for entries like Timeout waiting for integration response or Integration request failed—these will pinpoint whether the issue is API Gateway failing to trigger Lambda, or waiting too long for a response.

If your Lambda is deployed inside a VPC, network issues are a common timeout cause:

• Ensure your Lambda has enough elastic network interfaces (ENIs) available—if there are no free ENIs, Lambda can’t spin up an instance to process the request.
• Verify your Lambda’s security group allows outbound access to DynamoDB: either use a VPC endpoint for DynamoDB (recommended) or allow outbound traffic to the internet (if you’re using DynamoDB’s public endpoint).
• If using a VPC endpoint, confirm its security group allows inbound traffic from your Lambda’s security group.

内容的提问来源于stack exchange，提问作者Ryan Gibbs