Configuring AWS API Gateway: where production breaks
API gateway problems rarely look like an outage — they arrive as client-side errors. At peak, the entry point hits the limit of concurrent requests, the backend response exceeds the allotted timeout, and the client sees a connection drop.
It retries the request — and adds load to a service that is already at its limit. On a test environment with a smooth traffic profile, this does not reproduce: there is no contention for connections and no bursts.
The second source of failures is authorization desynchronization. Token signature is verified at the edge, while the identity provider's public keys are fetched and cached according to their own rules.
After key rotation or permission revocation, some requests return "access denied" even though the token itself is formally valid. Diagnostics are complicated by the fact that some routes let the request through and some do not.
The third class is lost requests between services. The call timed out, a response was sent to the client, but the operation on the service side was left without a result: the discrepancy is discovered through complaints, not logs.
It is fixed with an end-to-end request ID in every service integration and retries that check operation idempotency rather than executing it blindly.
Configuring AWS API Gateway rests on discipline: token verification before routing, rate limiting per client, timeouts shorter than client timeouts, route separation for different traffic profiles, and a unified error format. We explain how this is covered when the gateway is delivered turnkey.
Effect of moving traffic to a managed gateway
A managed gateway accepts traffic before it reaches applications, and this changes system behavior under peak load.
Rate limiting per route and per client key prevents a burst from one source turning into an overall increase in response time: at peak it plateaus, while excess requests receive a predictable rejection instead of dragging down the entire service.
Token and permission verification moves to the edge. The application stops spending resources on requests with an expired signature and incorrect access scope — the share of authorization errors becomes a separate gateway metric rather than noise in service logs.
Only a filtered stream reaches the interior, so API stability increases because invalid requests simply never reach the code.
Gateway fault tolerance rests on multiple entry points and a declarative description of routes.
The loss of one availability zone does not turn into service downtime — traffic goes to the others, and configuration is stored as code, so rolling back to the previous version of routes takes minutes rather than hours of manual console edits under pressure.
Request observability closes another class of failures: latency per route, share of error responses, and the full request path are visible.
We catch degradation at the stage of growing latency, not after user complaints — the scenario "the service went down because of one heavy client" ceases to be possible.
REST, HTTP, and private gateways: what to choose
On AWS, the same route can be deployed in three ways, and the difference becomes visible not on day one but as load grows and internal consumers are connected. An HTTP gateway serves requests with minimal latency and minimal configuration: routing, authorization, rate limiting.
REST provides access keys, usage plans, response caching, and request body validation before it reaches the service — you pay for this with slightly higher latency and configuration volume.
The private option publishes the route only inside a private network: from the outside, the address simply does not exist.
It is more convenient to choose the gateway type based on the consumer. If requests come from browsers and mobile applications and a legacy contract with keys and caching is required, choose REST.
For a new service with simple routes, HTTP is sufficient: fewer entities in configuration, deploys faster. The internal service perimeter is closed with a private gateway, traffic does not leave the network, and access is managed by policies.
Separately, keep the limitations in mind: some settings are incompatible between modes, and changing the gateway type later means rebuilding routes and authorization.
How the modes differ in practice
| Option | When it fits | Limitations |
|---|---|---|
| HTTP gateway | New services, simple routes, high request rate | No access keys or usage plans, no response cache, some request transformations unavailable |
| REST gateway | Legacy contracts, keys, cache, request validation at the edge | More entities in configuration, higher invocation latency |
| Private gateway | Internal service perimeter, access only from a private network | Unavailable to public consumers, requires connection endpoints and an internal load balancer |
| Hybrid scheme | Gradual migration: old on REST, new on HTTP | Dual operation, separate limits and monitoring |
Configuration and validation: gateway implementation stages
Work proceeds in a fixed order: each stage ends with an artifact that can be checked before moving to the next. This way the gateway does not turn into a black box between clients and services, and any configuration change remains explainable and rollbackable.
- API infrastructure audit. We inventory addresses and clients, analyze current authorization schemes, and capture a daily traffic profile. The output is a route map and a list of bottlenecks: duplicate paths, token verification inside each service, inconsistent error formats.
- Routing scheme design. For each perimeter, we choose the gateway mode, path matching rules, and versioning so old clients do not break when a new version of the service is released.
- Configuration. Per-client request rate limits, authorizers, request and response transformation, unified error format, timeout handling to the backend.
- Validation in the test environment. Functional scenarios plus failures: service unavailability, expired token, exhausted limit. We record the expected response code for each case.
- Gateway load testing. We reproduce the production profile, review latency, error rate, and what we hit first — limits, backend, or gateway.
- Handover to operations. Configuration is stored as code, metrics and alerts are configured, and the on-call shift has instructions for typical failures and the rollback procedure.
At each step you see the current result, not a report at the end. There is one acceptance criterion: the gateway withstands peak load, responds correctly when services fail, and is handed over to the team so that its changes do not require us.
Deliverables: schemas, policies, procedures
We hand over the package not as an archive of "how it turned out" but as a set of artifacts from which the gateway can be recreated and handed over to another team without verbal explanations.
Each item is a working file in version control, not a section in a description: changes are reviewed and deployed reproducibly, and manual edits in the web console are excluded.
- Schemas and configurations — declarative description of the gateway, stages, routes, and connections to internal services: the environment is built from code, and discrepancies between environments are visible at the validation stage.
- Routing schema — a map of methods and paths indicating where each call goes, how the request and response are transformed, where the failure points and fallback directions are.
- API access policies — authorization rules: token verification, access scope separation, request rate limits separately per client and per method.
- Roles and access rights — separation of rights between services, engineers, and the build system: each party has the minimum required set, and granting and revocation are described step by step.
- API gateway documentation — a list of routes, request and response schemas, error codes, and call examples; it is generated from the specification, so it does not diverge from the configuration.
- Operations procedure — the procedure for releasing changes, rolling back configuration to the previous version, actions during degradation of an internal service, who is responsible for access, and the response timeframes.
- Set of metrics and alerts — which indicators we collect, at what thresholds the signal triggers, who receives it, and according to which scenario the incident is investigated.
Case study: how the gateway removed peak load from services
Before: an entry point in every service
Services accepted external traffic directly — each verified tokens itself, counted request limits itself, and responded to bursts itself.
During peak hours, when a newsletter went out or a promotion started, ingress load grew 8-12 times: requests queued up, and the share of error responses held around 4%.
Incident analysis ran into the same issue — it was impossible to quickly determine whether a request did not arrive, hung during access verification, or failed in business logic.
What we rebuilt
The entry point was moved to AWS API Gateway: JWT verification, rate limiting, and routing now happen before the backend is invoked, so invalid requests never reach the services at all.
Frequent reads are served from the gateway-level cache, and per-route metrics — response codes, processing time, failure rate — are collected in one place instead of a dozen scattered logs.
What changed in the metrics
After traffic migration, the share of 5xx errors decreased from ~4% to 0.3%, and the 95th percentile response time dropped by about a third.
The gateway sustains a peak 12 times above average without scaling the services: only the entry point scales, while the backend operates in a steady mode.
The order of magnitude matches industry measurements — moving access verification and limits to the edge consistently yields a multiple reduction in failures.
How do quotas differ from rate limiting?
A quota is a counter over a long horizon: how many requests a consumer is entitled to make per day or month. It is tied to an access key and lives in a usage plan, and when exhausted the service responds with a rejection even if resources are completely free.
Request rate limiting solves a different problem: how many calls the service accepts per second right now.
This mechanism maintains two values — a steady rate and burst capacity. The reserve is replenished evenly: a short series of calls goes through using the accumulated reserve, while a flow above the norm begins to be dropped. This way burst protection does not penalize a client for a batch of requests instead of one.
A quota alone is not enough: a consumer will use up the daily limit in a minute and bring down the backend. Smoothing alone is also not enough: a client with a steady flow will hold the channel for days and crowd out others. The quota defines fairness between consumers, smoothing defines the service's capacity limit.
They are configured on different bases. We calculate the quota from the consumer's business weight, and rate limiting from backend throughput and response time.
Traffic priorities are separated by keys and plans: interactive scenarios get a larger burst reserve, while background exports get a low steady rate.
In monitoring, we count failures separately: an exhausted quota is a reason to revisit agreements with the consumer, while triggered smoothing is a signal that the backend is at its limit or the client is sending requests in batches.
A single shared counter erases this difference, and it is unclear what to change — the limit or the calling code.
Common technical concerns before implementation
Concerns before implementation are usually the same: will traffic be interrupted at the moment of switching, what happens with a sharp increase in the number of requests, how to change the authorization scheme without rewriting clients, and who takes on operations after handover. Below are short answers on each of these points so the decision is not made on assumptions.
How to migrate traffic without downtime?
We run two perimeters in parallel: the old one receives the entire flow, the new one receives a copy and processes it using the same logic. Then we increase the weight of the new route in steps and at each step compare the share of successful responses and processing time.
If the metrics deviate from baseline, the weight is returned with a single configuration change; rollback does not require deploying code.
What happens with a sharp increase in requests?
Configuring AWS API Gateway is built around limits: rate limiting at the method level, separate usage plans for external consumers, thresholds per access key. A burst above the limit is returned as a 429 with a retry-after header, rather than bringing down the backend.
Alerts for the share of 4xx and 5xx and for approaching the ceiling arrive before degradation becomes noticeable to clients.
Can the authorization scheme be changed without rewriting clients?
Yes — the old and new authorizers work simultaneously, and routes are migrated in groups. Clients migrate gradually, failures of the old scheme are logged and investigated individually.
When there are no remaining calls to the previous authorizer, it is removed along with the related policies.
What remains with the team after handover?
Infrastructure as code, route and authorization scheme descriptions, dashboards and alert rules, incident response procedures, and analysis of typical failures.
The customer's engineers receive a configuration walkthrough and support for the first changes; after that, the team runs the gateway independently.
Let's discuss the task: we will return with an estimate and plan
To return with an estimate and implementation plan rather than general considerations, we need your current picture: which services sit behind the gateway, what traffic goes through public routes, where authorization and rate limiting are already configured.
Describe the API gateway task in your own words — that is enough, and we will clarify the rest with questions.
Based on the assessment, you receive:
- a routing scheme for your traffic: REST or HTTP gateway for each type of load, with justification for the choice
- a JWT authorization design: where the signature is verified, how access scopes and roles are passed
- rate limiting policies by keys and quotas so that a burst from one consumer does not bring down the others
- an estimate of the scope of work by stages and an implementation plan with checkpoints at each step
- a set of metrics, logs, and alerts: latency, error rate, limit triggers
- an API infrastructure support procedure and a gateway development plan for the next horizon
- a migration option without downtime and a rollback point to the current configuration
The constraints worth mentioning upfront — peak bursts, availability requirements, external consumers, and legacy services behind the gateway: they have the greatest impact on the scope of work and the order of stages.
Write to us about what already works and what is getting in the way: we will prepare an estimate and return with a stage-by-stage plan. After that, we proceed in iterations — first a working perimeter on production traffic, then fine-tuning of limits and observability.