Context
A REST API can return 429 Too Many Requests when request demand crosses a throttling boundary. API Gateway has several such boundaries, including client usage plans, method or stage settings and Regional account capacity. Increasing one visible setting may have no effect if another boundary remains lower or the backend itself returns the response.
Capture one controlled request path
Record the REST API ID, deployed stage, resource method, client identifier, usage plan and integration. Collect request IDs, timestamps and response evidence without logging API key values. Confirm that the investigation concerns a REST API because HTTP API configuration differs.
Measure average request rate and short bursts separately. Token-bucket throttling considers both ongoing rate and burst capacity, so a modest minute average can hide concentrated submissions. Identify shared account workloads that may consume Regional capacity during the same interval.
1. Determine who produced the 429
Correlate gateway access evidence with integration logs and backend responses. Establish whether API Gateway rejected the request before integration or forwarded a 429 from the downstream service. Keep the gateway's request identifier in the incident record so the same request can be followed across boundaries.
Inspect retries from clients and intermediaries. A client that immediately resubmits every throttled request can amplify the burst. Record the attempted rate as well as the successful rate; the latter alone can hide retry pressure.
2. Compare all applicable settings
Read the usage plan's stage associations, default throttling, method overrides and quota. Check method or stage settings, account-level quotas and relevant AWS Regional constraints. AWS documents an application order for these layers, but a generous usage plan does not make the account pool unlimited.
Check which API stages share a client's usage-plan quota. An API key can identify a client across associated stages, so activity elsewhere in that plan can explain a surprising limit. Keep actual API authentication and authorization independent from the API key.
3. Use the pattern to guide correction
| Evidence | Likely boundary | Next action |
|---|---|---|
| One client is affected | Usage-plan or client burst behavior | Inspect plan association and retries |
| One method is affected | Method override or backend | Compare method settings and integration |
| Several APIs spike together | Shared Regional account capacity | Review aggregate demand |
| Backend sees the rejected requests | Downstream response may be 429 | Inspect backend limit |
An explicitly illustrative scenario: a reporting client sends its entire hourly batch at once. Its per-minute average appears low, yet a method-level burst target is exceeded. The team spreads submissions and adds bounded backoff with jitter, then reviews whether the method's capacity target matches the backend. Raising the usage-plan quota alone would not smooth the burst.
Correct and verify within the capacity contract
Apply the smallest justified setting or client correction in a test stage. Use a bounded load test with the real burst shape. Compare gateway throttles, backend latency, errors and downstream saturation. A higher accepted rate is useful only if the backend continues meeting its service objective.
The SOP should document effective limits, shared-account dependencies, client backoff and escalation for quota changes. AWS describes usage-plan throttles and quotas as best effort, so do not treat them as exact spending caps or security authorization. Monitor aggregate demand and costs separately, and recheck method overrides after new stages or API methods are deployed.
Explore Clouvenix cloud architecture for implementation and operational handover.
Technical reference
REST usage plans explains client quotas and API-key boundaries. REST throttling documents token buckets and limit layers.