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.
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 withRetry-After. - Make .NET clients behave well under throttling: honour
Retry-After, back off with jitter, and never retry non-idempotent requests blindly.
Prerequisites
- API Gateway: REST vs HTTP vs WebSocket — account-level throttling numbers
- IAM/SigV4 authorisation and mTLS — real authentication for machine callers
- Calling partner APIs safely — retries and circuit breakers
- Tools: .NET 10 SDK (or Docker); AWS CLI v2 with
learn-sandboxfor the optional deploy
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:
| Layer | Where you set it | Applies to | Notes |
|---|---|---|---|
| AWS Regional | AWS | Everyone in the Region | You can't change it |
| Account per Region | Service Quotas | All REST, HTTP and WebSocket APIs in the account | Default 10,000 requests per second, burst 5,000 (lower in some newer Regions); rate can be increased, burst is set by AWS |
| Stage / method | Stage settings (REST: per method too; HTTP: default route and per route) | That stage or route | Can't exceed the account limit |
| Usage plan (REST only) | Usage plan, per API stage, optionally per method | Each API key in the plan | Plus 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 equivalent | What's different |
|---|---|---|
APIM rate-limit-by-key policy | Usage plan throttle per API key; ASP.NET Core rate limiter partitioned by customer | API Gateway can only key on the API key; anything else (customer, token claim) needs your code or a Lambda authorizer |
APIM quota-by-key | Usage plan quota (day, week, month) | Best-effort, not a hard billing guarantee |
| APIM subscriptions and subscription keys | API keys in usage plans | APIM subscriptions often double as auth; on AWS, keys never should |
| APIM products | Usage plans (Basic, Premium tiers) | A usage plan spans one or more API stages |
| Azure Front Door WAF rate limit | AWS WAF rate-based rule | Evaluation windows 60–600 s; aggregation by IP, header and more |
AddRateLimiter in ASP.NET Core | Same | Unchanged — 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-1Infrastructure as Code
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).
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 429A 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.
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:
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
TokenBucketRateLimiterfromSystem.Threading.RateLimitingimplements the same algorithm API Gateway uses, which makes it a good teaching model.TokenLimit = 10is the burst — the bucket's capacity.TokensPerPeriod = 5perReplenishmentPeriod = 1 sis the rate.QueueLimit = 0makes the limiter reject immediately. API Gateway doesn't queue requests; it returns 429.AcquireAsync(1)takes one token;IsAcquiredtells you whether it got one. Always dispose the lease.- In the client,
pipeline.AddTimeout(30 s)is the outer budget: a client that waits patiently through threeRetry-After: 10responses still gives up within 30 seconds. ShouldRetryAfterHeader = truemakes Polly wait for the server'sRetry-After;MaxDelaycaps it so a misbehaving server can't park your thread for an hour.ShouldHandleretries 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.- On the server,
RateLimitPartition.GetFixedWindowLimiter(key, ...)creates one limiter per customer. A noisy customer exhausts only their own window. UseRateLimiter()afterUseAuthentication()— the partition key comes from the authenticated user. Before authentication,http.Useris empty and everyone would share the IP partition.OnRejectedwrites an RFC 9457 problem withRetry-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-Afterand 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
apiKeyRequiredand 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
| Symptom | Likely cause | Fix |
|---|---|---|
403 Forbidden with x-api-key present | Key not in a usage plan for this stage, key disabled, or wrong stage | get-usage-plan-keys; check the plan's API stages |
| 403 with no key | Method requires a key | Send x-api-key, or remove the requirement |
429 Too Many Requests at low traffic | Usage plan quota exhausted, or method limit set very low | get-usage; check method overrides on the stage |
429 Limit Exceeded for one key only | Per-key throttle in the usage plan | Move the partner to a higher tier or tune the plan |
| Limits seem ignored | Change made but API not redeployed (method settings), or best-effort tolerance | Redeploy; test with sustained, not single-second, load |
| App returns 429 to all customers at once | Limiter partitioned by IP behind a proxy, so all traffic shares one IP | Partition 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-1A 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 withWebApplicationFactory. - 🔴 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
The first burst still accepts 10 (the bucket starts full). After three seconds at 2 tokens per second, six tokens have been added, so the second burst accepts 6 and rejects 24. The cap only matters when the pause is long enough to refill past it: rate × pause versus burst.
Add o.AddPolicy("statements-per-customer", http => RateLimitPartition.GetFixedWindowLimiter(customerKey, _ => new FixedWindowRateLimiterOptions { PermitLimit = 5, Window = TimeSpan.FromHours(1) })) and chain .RequireRateLimiting("statements-per-customer") on the POST endpoint (an endpoint policy overrides the group's). The test posts six times with distinct idempotency keys and asserts that the sixth returns 429 with Retry-After. Why per endpoint: statement generation is expensive; reads are cheap, so they deserve different budgets.
Today: the stage limit of 20 rps was sized for a lab, not payday. Check the backend's real capacity (core adapter, Lambda concurrency, DynamoDB), raise the method limit for GET /v1/accounts to what the backend can sustain with headroom (for example 1,500 rps with an appropriate burst), keep the POST limit low, and confirm the account limit (10,000 rps) is not a factor. Ask the mobile team to confirm the app honours Retry-After. This month: add response caching for balances where acceptable (a few seconds), load-test with payday volumes, add a 429-rate alarm from access logs, and agree limits per consumer with the product owner rather than one stage-wide number.
Knowledge check
Answer: Yes — if the client's API key is in a usage plan with a lower per-key limit or an exhausted quota, or if a method override for that path is lower. The most specific layer applies first.
Answer: They identify a client for metering but prove nothing about the caller; they don't expire, are easy to leak through logs, and a key valid for one API in a usage plan works for all APIs in that plan. Use IAM, Cognito, Lambda authorizers or mTLS for access control.
Answer: The capacity of the token bucket — how many requests can be served in a short spike before the steady-state rate takes over.
Answer: HTTP APIs have no usage plans. Switch to a REST API, or implement quotas yourself (a Lambda authorizer or backend logic with a shared counter store), optionally plus WAF rate-based rules.
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-Afteror back off exponentially with jitter, cap retries and total time, and only retry idempotent requests.
Certification practice
A company exposes a REST API to partners and must limit each partner to 1,000 requests per day and 10 requests per second, and report each partner's usage. Partners already authenticate with a Lambda authorizer. What should the developer implement?
A. Stage-level throttling of 10 rps. B. A usage plan with throttling and a daily quota, one API key per partner, and API key required on the methods (or an AUTHORIZER key source). C. AWS WAF rate-based rules per partner IP. D. Reserved concurrency of 10 on the backend Lambda function.
Answer: B. Usage plans provide per-key throttles, quotas and usage reports. A limits everyone together. C counts IPs over minutes, not daily quotas per partner. D limits concurrency, not request rates per partner.
An API Gateway REST API fronts an on-premises system that can handle 200 requests per second. Traffic spikes to 1,000 rps for a few seconds several times a day. Clients can retry. What is the most cost-effective way to protect the backend?
A. Set method throttling below 200 rps with an appropriate burst and make clients retry with backoff on 429. B. Increase the account-level throttling quota. C. Put an Application Load Balancer in front of API Gateway. D. Enable API Gateway caching for POST requests.
Answer: A. Throttling at the gateway caps load on the backend, and client backoff smooths spikes. B raises limits. C adds cost and doesn't throttle. D: caching is for GET responses.
A security review finds that a REST API's only access control is an API key required on every method. What is the best remediation?
A. Rotate the API key monthly. B. Add an IAM, Cognito or Lambda authorizer to the methods and keep API keys only for usage plans. C. Move the key to a query string parameter. D. Increase the key length to 128 characters.
Answer: B. API keys aren't an authentication mechanism. A and D still leave a shared bearer string as the only control. C makes leaks via logs more likely.
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.
Calling partner APIs safely: egress, secrets, timeouts, retries and circuit breakers
Call external partners such as a sanctions-screening or credit-reference API from AWS with controlled egress, cached secrets, outbound mTLS and a tested Microsoft.Extensions.Http.Resilience pipeline that respects partner rate limits.
Calling AWS APIs from C#: the SDK and a hand-written SigV4 signer
Configure AWS SDK for .NET v4 clients properly (credentials, Region, retries, timeouts, paginators, DI), then sign an AWS request by hand with Signature Version 4 so you understand exactly what the SDK does and can debug SignatureDoesNotMatch errors.