API Gateway HTTP API vs REST API: Every Feature Difference, Pricing ($1.00 vs $3.50), Timeouts, the Payload 2.0 Lambda Trap, and Which to Choose

HTTP API vs REST API in Amazon API Gateway: both put an HTTPS endpoint in front of Lambda functions or other backends, but an HTTP API is the lean, cheaper option, $1.00 per million requests in US East against $3.50 for a REST API, with built-in JWT authorizers and automatic deployments, while a REST API has the full feature set: API keys and usage plans, per-client throttling, request validation, caching, AWS WAF, private endpoints, X-Ray tracing, canary releases and response streaming. Choose an HTTP API unless you need one of those REST-only features. The catch nobody mentions until it bites: an HTTP API sends Lambda a different event by default (payload format 2.0), so a function written for a REST API crashes on its first request with KeyError: 'httpMethod', and repeated query parameters arrive as one comma-joined string. To create an HTTP API for a Lambda function, one command is enough: aws apigatewayv2 create-api --name orders --protocol-type HTTP --target FUNCTION_ARN.

Ethan built the shop's first API, a small endpoint for the order-tracking page, as a REST API, because that was what the tutorial used. A year later he looked at the bill, saw the per-request price, and moved it to an HTTP API in an afternoon. The new endpoint returned 502 for every request. Nothing was wrong with the API. The Lambda function was still reading event["httpMethod"], a field that HTTP APIs do not send.

This guide compares API Gateway's HTTP APIs and REST APIs feature by feature, with current prices, the limits that differ, a worked cost example, the Lambda event difference that breaks migrations (tested with the official sample events), and a decision checklist. If API Gateway itself is new to you, what Amazon API Gateway is explains routes, stages and integrations first.

HTTP API vs REST API: the short version

The names confuse everyone, so start there. Both products serve RESTful APIs over HTTPS. "REST API" is API Gateway's original, full-featured product (sometimes called v1, because its control-plane API is apigateway). "HTTP API" is the newer, lighter product (v2, managed through the apigatewayv2 API, which also handles WebSocket APIs). The difference is not REST versus something else; it is a feature-rich product against a cheap, fast, minimal one.

• HTTP API: proxy requests to Lambda or HTTP backends, authorize with JWT (Cognito or any OIDC provider), IAM or a Lambda authorizer, CORS, custom domains, automatic deployments. Nothing more, at a lower price.
• REST API: everything above (except native JWT authorizers and Cloud Map integrations) plus API management (API keys, usage plans, per-client throttling, a developer portal), request validation and body transformation with mapping templates, caching, AWS WAF, resource policies, private and edge-optimized endpoints, X-Ray, execution logs, canary releases, mock integrations and response streaming.

For a typical "Lambda behind an HTTPS endpoint" app, an HTTP API does everything you need. You move up to a REST API the moment you need one of its specific features, and the list of those is short and concrete.

HTTP API vs REST API feature comparison

What an HTTP API gives you

HTTP APIs were designed for the common case: an HTTPS front door for Lambda functions and HTTP services, at the lowest price and latency. What you get, and what makes them pleasant to use:

• JWT authorizers built in. Point the authorizer at your Cognito user pool or any OpenID Connect issuer, set the audience, and API Gateway validates tokens before your function runs, with no Lambda authorizer to write. The Cognito authorizer 401 guide covers the token mistakes that cause rejections.
• Automatic deployments. The $default stage can deploy every change at once; no "Deploy API" step to forget.
• Simple routing. Routes like GET /orders/{id} or a catch-all $default route, with greedy path variables.
• CORS as a setting, not something you assemble from mock integrations and gateway responses.
• Cloud Map integrations for services discovered through AWS Cloud Map, which REST APIs cannot do.
• A simpler Lambda contract (payload format 2.0), where returning plain JSON is enough; see below.

What only a REST API can do

Each REST-only feature is a reason to pay the higher price, and each maps to a concrete need:

• You sell or meter API access: API keys, usage plans, quotas and per-client throttling, plus a developer portal for consumers.
• You need AWS WAF on the API itself (rate-based rules, managed rule groups, IP sets). With an HTTP API, you would put CloudFront with WAF in front instead.
• You need a private API reachable only from your VPCs through an interface endpoint, or a resource policy limiting callers by account, IP range or VPC endpoint.
• You want API Gateway to reject bad requests before they reach your code (request validation against a JSON schema) or to reshape requests and responses with mapping templates, including direct integrations with services like DynamoDB or SQS.
• You need caching at the API layer, X-Ray tracing through the gateway, execution logs, canary deployments, or response streaming for long, incremental responses.
• You need an edge-optimized endpoint, which routes callers through CloudFront edge locations to a single Regional API.

If none of these lines describes your project, the extra $2.50 per million requests buys you nothing. API Gateway 429 throttling explains how account, stage and usage-plan limits interact on REST APIs.

HTTP API vs REST API pricing

Prices from the API Gateway price list for US East (N. Virginia), October 2026:

Two details change the math. HTTP API requests are metered in 512 KB increments, so a 1.2 MB upload counts as three requests; REST API requests are counted once each. And both add the usual data transfer out charges. For Ethan's order-tracking endpoint, about 12 million requests a month of small JSON:

REST API:  12 million x $3.50 per million = $42.00 a month
HTTP API:  12 million x $1.00 per million = $12.00 a month
Saving:    $30.00 a month (71 percent), $360 a year, for the same Lambda function

At 500 million requests a month the gap grows in dollars: a REST API costs 333 million requests at $3.50 plus 167 million at $2.80, or $1,633.10, against an HTTP API's 300 million at $1.00 plus 200 million at $0.90, or $480.00. The REST cache, if you add one, is billed every hour whether or not it is hit: the smallest cache is $0.02 an hour, about $14.60 a month.

Timeouts, payload size and other limits that differ

The timeout row decides some migrations on its own. If your REST API depends on an integration timeout above 29 seconds (a quota increase on a Regional API), an HTTP API cannot match it: 30 seconds is its ceiling. For anything slow, the better pattern on either type is to return quickly and finish the work asynchronously; the 504 timeout guide shows how.

The Lambda event: payload format 1.0 vs 2.0

This is the part that breaks migrations. A REST API always sends Lambda payload format 1.0. An HTTP API sends format 2.0 by default (you can choose 1.0 per integration). The two events have different shapes. Running the official sample event of each format through two handlers, one written the REST way and one that handles both, gave:

event-v1.json -> rest_style_handler: {"method": "GET", "hello": "value"}
event-v1.json -> portable_handler: {"method": "GET", "path": "/my/path", "cookies": 0, "qs": {"parameter1": "value1", "parameter2": "value"}}
event-v2.json -> rest_style_handler: KeyError: 'httpMethod'
event-v2.json -> portable_handler: {"method": "POST", "path": "/my/path", "cookies": 2, "qs": {"parameter1": "value1,value2", "parameter2": "value"}}

Behind an API, that KeyError becomes a failed invocation and the client sees an error instead of data, which is exactly what Ethan's migrated endpoint did. The differences that matter:

A handler that works behind both, in Python:

import json

def handler(event, context):
    if event.get("version") == "2.0":                     # HTTP API, payload format 2.0
        method, path = event["requestContext"]["http"]["method"], event["rawPath"]
        cookies = event.get("cookies", [])
    else:                                                 # REST API, payload format 1.0
        method, path = event["httpMethod"], event["path"]
        cookies = [c.strip() for c in (event.get("headers") or {}).get("Cookie", "").split(";") if c.strip()]
    qs = event.get("queryStringParameters") or {}
    return {"statusCode": 200, "headers": {"content-type": "application/json"},
            "body": json.dumps({"method": method, "path": path, "cookies": len(cookies), "qs": qs})}

The other way out is to set the HTTP API integration's payload format version to 1.0, which makes the new API send the old event: the fastest fix for a migration, at the cost of keeping the older, more verbose format. Web frameworks running on Lambda through an adapter (Mangum, Serverless Express, Lambda Web Adapter and similar) usually handle both formats already. The 502 response-shape guide covers the response side in detail.

Example: the same Lambda API as an HTTP API and as a REST API

The quickest way to feel the difference is to create both for one Lambda function. An HTTP API has a "quick create": one command builds the API, a $default route, the Lambda integration and an auto-deploying stage:

aws apigatewayv2 create-api --name orders-http --protocol-type HTTP \
  --target arn:aws:lambda:us-east-1:111122223333:function:orders

# add a Cognito JWT authorizer (no Lambda authorizer needed)
aws apigatewayv2 create-authorizer --api-id a1b2c3 --name cognito --authorizer-type JWT \
  --identity-source '$request.header.Authorization' \
  --jwt-configuration Audience=1example23456789,Issuer=https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ExaMPle1

The REST API equivalent takes a resource lookup, a method, an integration and an explicit deployment:

aws apigateway create-rest-api --name orders-rest --endpoint-configuration types=REGIONAL
aws apigateway get-resources --rest-api-id r1                 # find the root resource id
aws apigateway put-method --rest-api-id r1 --resource-id root1 \
  --http-method ANY --authorization-type NONE
aws apigateway put-integration --rest-api-id r1 --resource-id root1 --http-method ANY \
  --type AWS_PROXY --integration-http-method POST \
  --uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:111122223333:function:orders/invocations
aws apigateway create-deployment --rest-api-id r1 --stage-name prod

Both sets of requests were checked against the current SDK models (botocore 1.43.118). Either way, the function also needs a resource-based permission that lets API Gateway invoke it (aws lambda add-permission with the apigateway.amazonaws.com principal); the console adds it for you, the CLI does not, and its absence is the classic cause of 500 errors with "Invalid permissions on Lambda function". To keep an existing function's format 1.0 code working behind the HTTP API, set the integration's payload format: aws apigatewayv2 update-integration --api-id a1b2c3 --integration-id int1 --payload-format-version 1.0.

Which one should you choose?

Work down this list; the first "yes" decides it.

1. Do you need API keys, usage plans or per-client quotas? REST API.
2. Do you need AWS WAF directly on the API, a resource policy, or a private API? REST API.
3. Do you need request validation, mapping templates, caching, X-Ray, canary releases, mock integrations or response streaming? REST API.
4. Do you need an integration timeout above 30 seconds? REST API (Regional or private, with a quota increase), or better, an asynchronous design.
5. Do you want JWT authorization without writing a Lambda authorizer, or Cloud Map integrations? HTTP API.
6. None of the above? HTTP API: lower price, less to configure.

For WebSocket connections, neither: that is the third API type, covered in REST API vs WebSocket API. And if all you need is an HTTPS URL for one Lambda function, with no routing or authorizers, a Lambda function URL costs nothing extra at all.

Migrating a REST API to an HTTP API, step by step

1. Check the REST-only list. If the API uses API keys, usage plans, WAF, a resource policy, validation, caching or a private endpoint, stop: either keep it on REST or replace that feature first (for example, WAF on a CloudFront distribution in front).
2. Make every Lambda function format-aware (the handler above), or plan to set payload format 1.0 on the new integrations.
3. Recreate authorizers. Cognito user pool authorizers become JWT authorizers (issuer is the user pool URL, audience is the app client ID); Lambda authorizers can stay, with the HTTP API's simple response format as an option.
4. Recreate CORS as an HTTP API setting, and remove the OPTIONS methods and gateway responses that REST needed.
5. Import or rebuild the routes. An OpenAPI definition exported from the REST stage can be imported into an HTTP API; review what it drops.
6. Test on the new endpoint with real requests, including repeated query parameters, cookies and error paths.
7. Switch the custom domain's API mapping from the REST stage to the HTTP API stage, so clients keep the same URL.
8. Watch errors for a day, then delete the REST API.

Ethan's migration, done in this order the second time, took an afternoon and saved $30 a month. "Thirty dollars for one afternoon," Jake said. "Do that again next month." Ethan explained that it only works once per API.

HTTP API vs REST API in AWS exams

Developer Associate and Solutions Architect questions use a few reliable signals:

• "Lowest cost", "lowest latency", "simple Lambda proxy", "JWT", "OIDC" point to an HTTP API.
• "API keys", "usage plans", "throttle each customer", "monetize the API" point to a REST API with usage plans.
• "Protect the API with AWS WAF" or "accessible only from a VPC" point to a REST API (WAF; private endpoint).
• "Cache responses to reduce backend load" points to REST API caching.
• "Validate request payloads before invoking the backend" points to REST API request validation.

Troubleshooting by symptom

Every request fails after moving to an HTTP API

The function reads format 1.0 fields such as httpMethod. Make it format-aware or set the integration's payload format to 1.0.

Query parameters arrive as "a,b" instead of a list

Payload format 2.0 joins repeated parameters with commas. Split them in code, or use format 1.0's multiValueQueryStringParameters.

My Cognito authorizer rejects valid tokens on the HTTP API

The JWT authorizer's audience must be the app client ID, and the issuer must be the exact user pool URL.

I cannot attach AWS WAF to my HTTP API

WAF supports REST APIs, not HTTP APIs. Put CloudFront with WAF in front, or use a REST API.

My HTTP API times out at 30 seconds

That is the hard maximum. Return quickly and finish the work asynchronously, or use a Regional REST API with a raised timeout.

The HTTP API bill is higher than expected for uploads

HTTP API requests are metered in 512 KB increments, so large request bodies count as several requests. Upload large files to S3 with presigned URLs.

Frequently asked questions

The order-tracking endpoint has run on the HTTP API ever since, with a JWT authorizer instead of the Lambda authorizer Ethan used to maintain. Jake noticed only one thing: the line on the bill got smaller. He asked whether there was a third kind of API that was cheaper still. Ethan said yes, a function URL, and that they would talk about it next year.

Revision note. Written October 23, 2026. "Cut your coat according to your cloth," the proverb says; with API Gateway, buy the REST features only when you will wear them.