API Gateway Lambda: How the Integration Actually Works

Pairing API Gateway with Lambda is the default way to expose a serverless function as an HTTPS endpoint on AWS. API Gateway handles the HTTP layer — routing, auth, throttling, request validation — and Lambda runs your code on demand without you managing servers. The two connect through an integration, and picking the right integration type is where most of the confusion (and bugs) come from.

If you're here because you're deciding whether to use this combination at all: yes, for most APIs that need to scale from zero with unpredictable traffic, it's a solid default. The rest of this article covers how the pieces fit together, the tradeoffs between integration types, and the mistakes that trip people up in production.

The two integration types

API Gateway supports two ways to call Lambda: Lambda proxy integration and Lambda custom integration. Almost everyone should use proxy integration.

Proxy integration passes the entire HTTP request — headers, query string, path parameters, body — to Lambda as a single JSON event, and expects Lambda to return a specific JSON shape back:

{
  "statusCode": 200,
  "headers": { "Content-Type": "application/json" },
  "body": "{\"message\":\"ok\"}"
}

Your Lambda function is responsible for parsing the event and formatting the response. This keeps API Gateway configuration minimal and puts all the logic in code, which is easier to test and version.

Custom integration (also called non-proxy) lets API Gateway map parts of the request to a different shape before it reaches Lambda, and map the Lambda output back through a response template. This is more flexible for transforming payloads without touching Lambda code, but it means logic lives in Velocity templates inside API Gateway configuration — harder to test, harder to read, and easy to get subtly wrong. Use it only if you have a real reason, like fronting a legacy Lambda you can't modify.

REST API vs HTTP API

API Gateway offers two product types that both integrate with Lambda: REST APIs (the original, feature-rich option) and HTTP APIs (newer, cheaper, simpler).

• HTTP APIs are roughly 70% cheaper per request, support JWT authorizers and Lambda authorizers, and cover most common use cases with less configuration.
• REST APIs support request validation, usage plans with API keys, WAF integration, private endpoints via VPC, and more granular request/response transformation.

If you're starting fresh and don't need the REST-API-only features, HTTP API + Lambda proxy integration is the simpler, cheaper path.

A minimal example

A typical setup with the AWS CLI or infrastructure-as-code involves three pieces: the Lambda function, an API Gateway route, and permission for API Gateway to invoke the function.

aws lambda add-permission \
  --function-name my-function \
  --statement-id apigateway-invoke \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:REGION:ACCOUNT_ID:API_ID/*/*/my-route"

Without this permission, calls will return a generic 500 with an "Internal server error" that gives no indication the problem is a missing invoke permission — one of the most common first-deploy failures.

On the Lambda side, a proxy-integration handler in Node.js looks like:

export const handler = async (event) => {
  const name = event.queryStringParameters?.name ?? "world";
  return {
    statusCode: 200,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ message: `Hello, ${name}` }),
  };
};

Cold starts and timeouts

Two operational realities shape how you design around API Gateway + Lambda:

• Cold starts. When a function hasn't run recently, Lambda has to initialize a new execution environment before running your code, adding latency — usually tens to hundreds of milliseconds, more for large deployment packages or languages with heavier runtime init (JVM, .NET). Provisioned concurrency removes this at a fixed hourly cost.
• Timeouts. API Gateway has a hard limit of 29 seconds per request, regardless of your Lambda's configured timeout. If your function can run longer than that, you need an async pattern (API Gateway triggers Lambda, which writes to a queue or database, and the client polls or uses WebSockets) rather than a synchronous request/response.

If you're building anything that calls a slow, streaming-capable LLM API from inside a Lambda-backed endpoint, this 29-second ceiling is worth checking early — it's a common reason teams end up needing a different architecture, or a dedicated API layer instead of gluing gateway and function together themselves.

When this pattern is a bad fit

API Gateway + Lambda is excellent for spiky, low-to-medium-volume traffic and event-driven APIs. It's a worse fit when:

• You have very high, sustained throughput — at that point, an always-on container behind a load balancer is usually cheaper per request.
• You need long-lived connections beyond WebSocket use cases — synchronous requests over ~29 seconds don't work.
• Your team wants one platform to manage instead of stitching together Lambda, API Gateway, IAM roles, and CloudWatch alarms by hand — a managed API layer or PaaS reduces that operational surface.

That last point is also why teams building on top of third-party APIs often skip rolling their own gateway entirely. If you're wrapping something like Claude behind an API for your own product, SubToAPI gives you application API keys (sub_live_...), streaming, tool use, and usage metadata out of the box — see the quickstart — without you standing up API Gateway, Lambda, and IAM policies just to get a working endpoint. Full request/response shapes are in the Messages docs, and streaming works the same way you'd expect from a normal HTTPS API.

Practical checklist

Before shipping an API Gateway + Lambda endpoint to production:

• Use proxy integration unless you have a concrete reason not to.
• Choose HTTP API over REST API unless you need REST-API-only features.
• Set Lambda timeout comfortably under 29 seconds, or redesign for async.
• Add lambda:InvokeFunction permission scoped to the specific API Gateway source ARN.
• Enable access logging on API Gateway — default logging is minimal and debugging blind is painful.
• Consider provisioned concurrency only after measuring real cold-start impact, not preemptively.

Questions

Does API Gateway call Lambda synchronously? Yes, in the standard proxy integration API Gateway invokes Lambda synchronously and waits for a response, subject to the 29-second API Gateway timeout regardless of the Lambda function's own timeout setting.

Is HTTP API or REST API better for Lambda? HTTP API is cheaper and simpler and covers most use cases; REST API is worth the extra cost and complexity only if you need features like usage plans, request validation, or VPC-based private endpoints.

Why does my API Gateway route return a 500 with no details? The most common cause is a missing lambda:InvokeFunction permission for the API Gateway source ARN — check IAM before debugging the function code itself.