Skip to Content
Cloud Engineering Academy
4. API Development & Integration

API keys, usage plans, throttling and rate limiting

Use API Gateway throttling, usage plans and API keys for what they are good at — metering and protecting capacity — add per-customer limits in ASP.NET Core, and handle 429s correctly on the client.

intermediate⏱ 1 h 15 min🟢 FreeDVA-C03SAA-C03SCS-C03

Assumes: .NET 10 LTS · System.Threading.RateLimiting (in-box) · Microsoft.Extensions.Http.Resilience 10.11.0 · Amazon.CDK.Lib 2.277.0 · Terraform AWS provider v6 · Region us-east-1. Verified against official sources on 2026-11-18.

Learning objectives

By the end of this lesson you can:

  • Explain the token bucket (rate and burst) and predict when API Gateway returns 429 Too Many Requests.
  • Describe the four layers of API Gateway throttling and their order: usage plan per client/method, stage/method, account per Region, AWS Regional.
  • Create a usage plan with throttling and a quota, attach an API key, and require the key on methods — and explain why an API key is not authentication.
  • Add per-customer rate limiting in ASP.NET Core with Microsoft.AspNetCore.RateLimiting, returning RFC 9457 errors with Retry-After.
  • Make .NET clients behave well under throttling: honour Retry-After, back off with jitter, and never retry non-idempotent requests blindly.

Prerequisites

Why this matters in banking

On payday morning Harbourline's mobile app refreshes balances for hundreds of thousands of customers within minutes. A buggy release of a budgeting partner's app polls GET /v1/accounts every second for every user. A fraudster runs a credential-stuffing script. All three look like "lots of requests". Without limits, the core banking system behind the API — often a mainframe with a fixed capacity and a cost per MIPS — slows down for everyone, and an outage on payday is a regulatory incident under operational-resilience rules.

Rate limiting is how you decide who gets capacity when demand exceeds supply: protect the core, keep each consumer within its contract, and tell clients clearly when to come back. Getting it wrong in the other direction is also costly: aggressive limits that throttle legitimate customers produce complaints and failed payments.

The idea in plain language

Throttling (rate limiting) caps how fast requests may arrive. Quotas cap how many requests a client may make in a longer period (a day, a week or a month). An API key is a long string that identifies which client is calling so that the right plan can be applied. A usage plan ties API keys to API stages with a throttle and a quota.

API Gateway implements throttling with a token bucket. A bucket holds up to burst tokens and is refilled at rate tokens per second. Each request takes one token. If the bucket is empty, the request is rejected with 429. A full bucket lets a short spike through; sustained traffic above the rate drains it.

Analogy: the bank branch's ticket machine. It refills with a fixed number of tickets per minute (rate), and the dispenser holds at most a set number (burst). When a coach party arrives, the first customers get tickets straight away; then everyone waits for refills. An API key is the loyalty card that tells the branch which queue you belong in — it doesn't prove who you are; anyone holding the card gets the same queue.

What problem the AWS service solves

API Gateway gives you capacity protection without code:

LayerWhere you set itApplies toNotes
AWS RegionalAWSEveryone in the RegionYou can't change it
Account per RegionService QuotasAll REST, HTTP and WebSocket APIs in the accountDefault 10,000 requests per second, burst 5,000 (lower in some newer Regions); rate can be increased, burst is set by AWS
Stage / methodStage settings (REST: per method too; HTTP: default route and per route)That stage or routeCan't exceed the account limit
Usage plan (REST only)Usage plan, per API stage, optionally per methodEach API key in the planPlus a quota per day/week/month

API Gateway applies them from the most specific to the most general: the usage plan's per-client or per-method limit first, then the stage's per-method limit, then the account limit, then the Regional limit. Throttles and quotas are targets applied on a best-effort basis: a client can occasionally exceed them. AWS explicitly says not to rely on them to control costs or to block access.

API keys — what they are and are not for. API Gateway's documentation is blunt: don't use API keys for authentication or authorisation. A valid key for one API in a usage plan gives access to all APIs in that plan; keys travel in a header (x-api-key) that is easy to log and copy; there is no expiry, no proof of possession and no user. Use keys together with real authentication (IAM, Cognito, a Lambda authorizer or mTLS) for one job: identifying the client for metering, throttling and quotas.

Quotas you should know (REST APIs, per account per Region): 10,000 API keys (not adjustable), 300 usage plans (adjustable), 10 usage plans per API key (adjustable), and 20 method-level throttling settings per stage in a usage plan. A key value is 20–128 characters. A key can be in several usage plans but in only one plan per stage.

HTTP APIs have stage and route throttling but no usage plans and no API keys. If you need per-client quotas on an HTTP API, implement them yourself (Lambda authorizer plus a counter store, or in the backend).

WebSocket APIs throttle connection and message rates at the stage/route level.

AWS WAF rate-based rules complement API Gateway throttling: they count per IP (or per header, per forwarded IP and so on) over a 1-, 2-, 5- or 10-minute window, minimum limit 10, and can block abusive sources before they consume your API Gateway throttle. The WAF lesson in this module covers them (see the module overview); the module project's HlM04-Waf stack uses one.

Microsoft / Azure comparison

You know (Microsoft/Azure)AWS equivalentWhat's different
APIM rate-limit-by-key policyUsage plan throttle per API key; ASP.NET Core rate limiter partitioned by customerAPI Gateway can only key on the API key; anything else (customer, token claim) needs your code or a Lambda authorizer
APIM quota-by-keyUsage plan quota (day, week, month)Best-effort, not a hard billing guarantee
APIM subscriptions and subscription keysAPI keys in usage plansAPIM subscriptions often double as auth; on AWS, keys never should
APIM productsUsage plans (Basic, Premium tiers)A usage plan spans one or more API stages
Azure Front Door WAF rate limitAWS WAF rate-based ruleEvaluation windows 60–600 s; aggregation by IP, header and more
AddRateLimiter in ASP.NET CoreSameUnchanged — it runs in your container or Lambda

Architecture

Each layer has a different key: WAF counts IP addresses, usage plans count API keys, stage limits count all traffic to a method, and only your application can count customers (from the validated token).

Step-by-step implementation

Size the limits from the backend, not from a guess

Start with what the slowest dependency can take. If the core banking adapter handles 50 requests per second and GET /v1/accounts makes one core call, the method limit must stay well below 50 rps across all callers, leaving headroom for batch jobs. Then split that budget: customers via the app, partners via usage plans, internal jobs via a separate private API.

Set stage and method throttling

On the REST API stage, set a default (for example 20 rps, burst 40), then override sensitive methods: POST /v1/accounts/{accountId}/statement-requests might get 5 rps, burst 10, because it triggers expensive statement generation. On an HTTP API, set default route throttling and per-route overrides.

Create usage plans and keys for partners

Create plans per contract tier — partner-standard (5 rps, burst 10, 50,000 per month) and partner-premium (25 rps, burst 50, 500,000 per month) — attach the API stage, create one key per partner application, and add the key to the plan. Mark the partner methods as API key required. Partners send the key in x-api-key in addition to their OAuth token or client certificate.

Alternatively, set the API's key source to AUTHORIZER: a Lambda authorizer returns usageIdentifierKey, so partners never handle the key at all — the authorizer maps the authenticated partner to its key.

Add per-customer limits in the application

API Gateway can't key on a customer ID inside a JWT. The module project partitions ASP.NET Core's rate limiter by the server-resolved customer_id claim (falling back to IP for anonymous calls) and answers 429 with ProblemDetails and Retry-After.

Make clients well-behaved

Every client — your app, partners' SDKs, your own services — must treat 429 and 503 as "slow down": honour Retry-After, otherwise back off exponentially with jitter, cap the number of retries, and retry only idempotent operations (GET, or POST with an Idempotency-Key, see idempotency keys).

Watch it

CloudWatch metrics for REST APIs include Count, 4XXError, 5XXError and Latency; there is no separate "throttled" metric, so put $context.status in access logs and count 429s with a metric filter or Logs Insights. For usage plans, get-usage returns per-key usage against the quota.

AWS Console instructions

  • Stage throttling: Console → API Gateway → APIs → (REST API) → Stages → learn → Stage details → Edit → Throttling: rate and burst. Per-method overrides: same page → Method overrides.
  • HTTP API route throttling: API → Protect → Throttling → edit the default route or a specific route.
  • Usage plan: API Gateway → Usage plans → Create → name, throttling (rate, burst), quota (requests per day/week/month) → Add stage → choose API and stage → optional method throttling → Add API key → create or select.
  • Require a key on a method: API → Resources → method → Method request → Edit → API key required → Save → Deploy API.

AWS CLI

API_ID=a1b2c3d4e5
STAGE=learn

# Stage-wide default for every method: 20 rps, burst 40.
aws apigateway update-stage --rest-api-id $API_ID --stage-name $STAGE \
  --patch-operations op=replace,path=/*/*/throttling/rateLimit,value=20 \
                     op=replace,path=/*/*/throttling/burstLimit,value=40 \
  --profile learn-sandbox --region us-east-1

# Tighter limit on one method. The resource path is escaped: '/' becomes '~1'.
aws apigateway update-stage --rest-api-id $API_ID --stage-name $STAGE \
  --patch-operations "op=replace,path=/~1v1~1accounts~1{accountId}~1statement-requests/POST/throttling/rateLimit,value=5" \
                     "op=replace,path=/~1v1~1accounts~1{accountId}~1statement-requests/POST/throttling/burstLimit,value=10" \
  --profile learn-sandbox --region us-east-1

# Usage plan for partners: 5 rps, burst 10, 50,000 requests per month.
PLAN_ID=$(aws apigateway create-usage-plan --name partner-standard \
  --throttle burstLimit=10,rateLimit=5 --quota limit=50000,period=MONTH \
  --api-stages apiId=$API_ID,stage=$STAGE \
  --tags Project=cea-lab,Lab=m04-l11,Environment=learn,Owner=learner \
  --query id --output text --profile learn-sandbox --region us-east-1)

# One key per partner application; API Gateway generates the value.
KEY_ID=$(aws apigateway create-api-key --name sentinel-credit-bureau --enabled \
  --tags Project=cea-lab,Lab=m04-l11,Environment=learn,Owner=learner \
  --query id --output text --profile learn-sandbox --region us-east-1)

aws apigateway create-usage-plan-key --usage-plan-id $PLAN_ID --key-id $KEY_ID --key-type API_KEY \
  --profile learn-sandbox --region us-east-1

# Usage so far this period, per key.
aws apigateway get-usage --usage-plan-id $PLAN_ID --start-date 2026-11-01 --end-date 2026-11-30 \
  --profile learn-sandbox --region us-east-1

# HTTP API: default route throttling on the $default stage.
aws apigatewayv2 update-stage --api-id h1t2t3p4a5 --stage-name '$default' \
  --default-route-settings ThrottlingRateLimit=20,ThrottlingBurstLimit=40 \
  --profile learn-sandbox --region us-east-1

Infrastructure as Code

PartnerUsagePlans.cs
using Amazon.CDK.AWS.APIGateway;
using Constructs;

namespace Harbourline.AccountInformation.Infra;

public static class PartnerUsagePlans
{
    /// <summary>Adds partner tiers to an existing REST API. Keys identify partners; they don't authenticate them.</summary>
    public static void Add(Construct scope, RestApi api, Method statementRequestPost)
    {
        var standard = api.AddUsagePlan("PartnerStandard", new UsagePlanProps
        {
            Name = "partner-standard",
            Throttle = new ThrottleSettings { RateLimit = 5, BurstLimit = 10 },
            Quota = new QuotaSettings { Limit = 50_000, Period = Period.MONTH },
        });

        standard.AddApiStage(new UsagePlanPerApiStage
        {
            Stage = api.DeploymentStage,
            // Method-level throttle inside the plan: the expensive POST gets less.
            Throttle =
            [
                new ThrottlingPerMethod { Method = statementRequestPost, Throttle = new ThrottleSettings { RateLimit = 1, BurstLimit = 2 } },
            ],
        });

        // One key per partner application. The value is generated by API Gateway and
        // shared with the partner out of band (never in source control).
        var sentinelKey = api.AddApiKey("SentinelKey", new ApiKeyOptions { ApiKeyName = "sentinel-credit-bureau" });
        standard.AddApiKey(sentinelKey);
    }
}

Methods that partners call need ApiKeyRequired = true in their MethodOptions, alongside the authorizer.

Complete code

Two runnable programs: a token-bucket simulator that shows exactly when a bucket rejects requests, and a well-behaved client that handles 429s. The server side lives in the module project (labs/m04-account-information-api/src/Harbourline.AccountInformation.Api/Hosting/RateLimiting.cs).

Harbourline.Throttling/Program.cs — token bucket simulator
using System.Threading.RateLimiting;

// API Gateway semantics: 'rate' tokens per second, bucket capacity 'burst'. One request = one token.
var bucket = new TokenBucketRateLimiter(new TokenBucketRateLimiterOptions
{
    TokenLimit = 10,                                  // burst
    TokensPerPeriod = 5,                              // rate: 5 per second
    ReplenishmentPeriod = TimeSpan.FromSeconds(1),
    QueueLimit = 0,                                   // reject instead of waiting, like a gateway
    AutoReplenishment = true,
});

// Scenario: a partner sends 30 requests as fast as possible, waits 2 s, then sends 30 more.
await Burst("first burst", 30);
await Task.Delay(TimeSpan.FromSeconds(2));
await Burst("after 2 s pause", 30);

async Task Burst(string label, int count)
{
    int ok = 0, throttled = 0;
    for (var i = 0; i < count; i++)
    {
        using var lease = await bucket.AcquireAsync(1);
        if (lease.IsAcquired) ok++; else throttled++;
    }
    Console.WriteLine($"{label,-16}: {ok,2} accepted, {throttled,2} rejected with 429");
}

Expected output (timing can shift by a token or two):

first burst     : 10 accepted, 20 rejected with 429
after 2 s pause : 10 accepted, 20 rejected with 429

A full bucket absorbs a spike of burst requests; after a pause of two seconds, five tokens per second have refilled it to its cap of ten (not fifteen), so the second spike behaves the same way.

Harbourline.Throttling/ThrottlingAwareClient.cs — client side
using System.Net;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Http.Resilience;
using Polly;

namespace Harbourline.Throttling;

public static class ThrottlingAwareClient
{
    /// <summary>
    /// Typed client for the Account Information API that slows down on 429/503:
    /// honours Retry-After, otherwise exponential backoff with jitter, at most 3 retries,
    /// and only for GET (safe) requests.
    /// </summary>
    public static IHttpClientBuilder AddAccountInformationClient(this IServiceCollection services, Uri baseAddress)
    {
        var builder = services.AddHttpClient("account-information", c => c.BaseAddress = baseAddress);
        builder.AddResilienceHandler("throttling", pipeline =>
        {
            pipeline.AddTimeout(TimeSpan.FromSeconds(30));      // total budget, including waits
            pipeline.AddRetry(new HttpRetryStrategyOptions
            {
                MaxRetryAttempts = 3,
                BackoffType = DelayBackoffType.Exponential,
                UseJitter = true,
                Delay = TimeSpan.FromMilliseconds(500),
                MaxDelay = TimeSpan.FromSeconds(10),            // never sleep longer than this, even if told to
                ShouldRetryAfterHeader = true,                  // use the server's Retry-After when present
                ShouldHandle = args => ValueTask.FromResult(
                    args.Outcome.Result?.RequestMessage?.Method == HttpMethod.Get &&
                    args.Outcome.Result.StatusCode is HttpStatusCode.TooManyRequests or HttpStatusCode.ServiceUnavailable),
            });
            pipeline.AddTimeout(TimeSpan.FromSeconds(5));       // per attempt
        });
        return builder;
    }
}

And the server side from the module project, condensed:

Hosting/RateLimiting.cs (excerpt from the module project)
services.AddRateLimiter(o =>
{
    o.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
    o.AddPolicy("per-customer", http =>
    {
        // Partition on the server-resolved customer; fall back to the client IP for anonymous calls.
        var key = http.User.FindFirst("customer_id")?.Value
                  ?? "ip:" + (http.Connection.RemoteIpAddress?.ToString() ?? "unknown");
        return RateLimitPartition.GetFixedWindowLimiter(key, _ => new FixedWindowRateLimiterOptions
        {
            PermitLimit = 120,
            Window = TimeSpan.FromMinutes(1),
            QueueLimit = 0,
        });
    });
    o.OnRejected = async (ctx, ct) =>
    {
        var retryAfter = ctx.Lease.TryGetMetadata(MetadataName.RetryAfter, out var after)
            ? (int)Math.Ceiling(after.TotalSeconds) : 60;
        ctx.HttpContext.Response.Headers.RetryAfter = retryAfter.ToString(CultureInfo.InvariantCulture);
        await ctx.HttpContext.RequestServices.GetRequiredService<IProblemDetailsService>().WriteAsync(new ProblemDetailsContext
        {
            HttpContext = ctx.HttpContext,
            ProblemDetails = new ProblemDetails
            {
                Status = 429,
                Type = "https://api.harbourline.example/problems/rate-limited",
                Title = "Too many requests",
                Detail = $"Retry after {retryAfter} seconds.",
            },
        });
    };
});

// Pipeline order: authentication first, so the limiter can see the customer.
app.UseAuthentication();
app.UseRateLimiter();
app.UseAuthorization();
// Endpoints opt in: app.MapGroup("/v1").RequireRateLimiting("per-customer");

The module project's test Fourth_request_in_the_window_is_429_with_retry_after_and_other_customers_are_unaffected proves both behaviours: the fourth request from Alice in a window of three gets 429 with Retry-After, while Bob is still served.

Code explained line by line

  1. TokenBucketRateLimiter from System.Threading.RateLimiting implements the same algorithm API Gateway uses, which makes it a good teaching model.
  2. TokenLimit = 10 is the burst — the bucket's capacity. TokensPerPeriod = 5 per ReplenishmentPeriod = 1 s is the rate.
  3. QueueLimit = 0 makes the limiter reject immediately. API Gateway doesn't queue requests; it returns 429.
  4. AcquireAsync(1) takes one token; IsAcquired tells you whether it got one. Always dispose the lease.
  5. In the client, pipeline.AddTimeout(30 s) is the outer budget: a client that waits patiently through three Retry-After: 10 responses still gives up within 30 seconds.
  6. ShouldRetryAfterHeader = true makes Polly wait for the server's Retry-After; MaxDelay caps it so a misbehaving server can't park your thread for an hour.
  7. ShouldHandle retries only GETs on 429/503. A POST that created a statement request may have succeeded before the 503; retrying it without an idempotency key could create a duplicate.
  8. On the server, RateLimitPartition.GetFixedWindowLimiter(key, ...) creates one limiter per customer. A noisy customer exhausts only their own window.
  9. UseRateLimiter() after UseAuthentication() — the partition key comes from the authenticated user. Before authentication, http.User is empty and everyone would share the IP partition.
  10. OnRejected writes an RFC 9457 problem with Retry-After, the same error shape as the rest of the API.

Security considerations

⚠ Learning shortcut — not for production

The in-app limiter keeps its counters in memory, per process. With several Fargate tasks or many Lambda execution environments, each instance has its own counters, so the real limit is "120 per minute per customer per instance". That's acceptable as a safety net behind API Gateway throttling, but if limits are contractual, use a shared store (for example a DynamoDB atomic counter or ElastiCache) or enforce them at the gateway with usage plans.

  • API keys are identifiers, not secrets. Never let a key alone authorise access; pair it with IAM, Cognito, a Lambda authorizer or mTLS. Rotate keys when a partner's staff changes, and disable unused keys.
  • Don't log keys. Access logs can include $context.identity.apiKeyId — the key's ID, not its value. Use that.
  • Throttling is not a WAF. Credential stuffing at 5 requests per second from 10,000 IPs passes every per-key and per-method limit. Use WAF rate-based rules, managed rule groups and Cognito's own protections.
  • Fail closed politely. Return 429 with Retry-After and a ProblemDetails body; never return 200 with an empty list, which a client would treat as "customer has no accounts".
  • Fairness and conduct. Throttling customers can have consumer-duty implications (for example blocking access to balances during an incident). Make sure customer-facing limits are generous and reviewed with the product and risk teams.

Banking use case

Harbourline publishes the Account Information API to three Open Banking-style aggregators. Each has an OAuth client (authentication), an API key in a usage plan matching its contract tier (metering and quota), and per-customer limits in the app (fairness). The finance team bills premium partners from get-usage exports. When one aggregator's release loops on GET /v1/accounts, it hits its own 5 rps plan limit and gets 429s; other partners and Harbourline's own app are unaffected, and the account-level limit is never approached. The monthly quota stops a runaway integration from consuming the year's agreed volume in a week.

Common mistakes

  • Using the API key as the only credential → anyone with the key is "the partner" → add real authentication.
  • Forgetting to mark methods "API key required" → usage plan limits never apply → set apiKeyRequired and redeploy.
  • Expecting usage plans on an HTTP API → they don't exist → use a REST API or implement limits in code.
  • Setting stage limits higher than the account limit → they can't take effect → raise the account quota first (Service Quotas).
  • Retrying 429s immediately in a tight loop → makes throttling worse for everyone → honour Retry-After, back off with jitter.
  • Relying on quotas for cost control → they are best-effort → use AWS Budgets alarms too.
  • Placing UseRateLimiter() before authentication → everyone shares IP partitions → order the middleware correctly.

Troubleshooting

SymptomLikely causeFix
403 Forbidden with x-api-key presentKey not in a usage plan for this stage, key disabled, or wrong stageget-usage-plan-keys; check the plan's API stages
403 with no keyMethod requires a keySend x-api-key, or remove the requirement
429 Too Many Requests at low trafficUsage plan quota exhausted, or method limit set very lowget-usage; check method overrides on the stage
429 Limit Exceeded for one key onlyPer-key throttle in the usage planMove the partner to a higher tier or tune the plan
Limits seem ignoredChange made but API not redeployed (method settings), or best-effort toleranceRedeploy; test with sustained, not single-second, load
App returns 429 to all customers at onceLimiter partitioned by IP behind a proxy, so all traffic shares one IPPartition by customer_id (after authentication) or by the real client IP from trusted forwarded headers

Cost and cleanup

Free. API keys and usage plans have no charge; you pay normal API Gateway request prices (REST APIs about USD 3.50 per million requests for the first tier in us-east-1), and throttled requests that are rejected by API Gateway are not billed as API calls ⚠ VERIFY. The simulator and client run locally.

If you created the CLI resources:

aws apigateway delete-usage-plan-key --usage-plan-id $PLAN_ID --key-id $KEY_ID --profile learn-sandbox --region us-east-1
aws apigateway update-usage-plan --usage-plan-id $PLAN_ID \
  --patch-operations op=remove,path=/apiStages,value=$API_ID:$STAGE --profile learn-sandbox --region us-east-1
aws apigateway delete-usage-plan --usage-plan-id $PLAN_ID --profile learn-sandbox --region us-east-1
aws apigateway delete-api-key --api-key $KEY_ID --profile learn-sandbox --region us-east-1
aws resourcegroupstaggingapi get-resources --tag-filters Key=Lab,Values=m04-l11 \
  --query "ResourceTagMappingList[].ResourceARN" --profile learn-sandbox --region us-east-1

A usage plan can't be deleted while it still has API stages, which is why the stage is removed first.

Exercises

  • 🟢 Guided: Run the simulator. Change the rate to 2 per second and the pause to 3 seconds. Predict the second burst's result before you run it.
  • 🟡 Challenge: Extend the module project's limiter with a second, stricter policy for POST /v1/accounts/{accountId}/statement-requests (5 per hour per customer) and write an xUnit test for it with WebApplicationFactory.
  • 🔴 Live problem: On payday at 07:00, the mobile team reports "random 429s"; API Gateway metrics show 2,000 requests per second on GET /v1/accounts, and the stage is set to 20 rps with a 40 burst for all methods. Product wants the errors gone "now". What do you change today, and what do you change this month?

Assignment

Write a rate-limit policy for the Account Information API: the limits at each layer (WAF, account, stage, method, usage plan tiers, per customer), how each number was derived from backend capacity, the client contract (429, Retry-After, retry rules), and the alarms. Add it to your portfolio repository with the simulator.

Solutions

Knowledge check

Interview questions

  • "How do you protect a legacy core system behind a public API?" Size limits from the core's capacity; stage and method throttling at the gateway; usage plans per partner; per-customer limits in the app; WAF rate rules for abuse; caching where data freshness allows; circuit breakers on the call to the core; clear 429/503 contracts with Retry-After.
  • "Are API keys secure?" They're identifiers, not authentication. Fine for metering and quotas alongside real authentication; dangerous as the only control.
  • "How should a client react to 429?" Stop, wait for Retry-After or back off exponentially with jitter, cap retries and total time, and only retry idempotent requests.

Certification practice

Completion checklist

  • I can draw the token bucket and explain rate vs burst
  • I can list the throttling layers in order of application
  • I can explain in one sentence why API keys aren't authentication
  • I ran the simulator and the module project's rate-limit test
  • I deleted any usage plans and keys I created

Key takeaways

  • API Gateway throttles with a token bucket: rate refills, burst is the capacity; 429 when empty. Limits are best-effort targets.
  • Layers apply from specific to general: usage plan per key/method → stage/method → account (10,000 rps, burst 5,000 by default) → Region.
  • API keys identify, they don't authenticate. Use them with usage plans for metering and quotas, alongside real auth. HTTP APIs have neither.
  • Only your app knows the customer: add per-customer limits after authentication, and make clients honour Retry-After.

Further reading

Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page