Fixing AWS API Gateway 429 Too Many Requests (Rate Limit) & Throttling Errors
Learn how to diagnose and fix AWS API Gateway rate limits (429), timeouts (504), not found (404), and service unavailable (503) errors using usage plans and Clo
- Account-level or default method throttling limits exceeded (default 10,000 RPS).
- Usage Plan quota or rate limits exhausted for a specific API Key.
- Backend integration timeouts (504) or service unavailability (503) causing cascading client retry storms.
- Quick fix: Check CloudWatch '4XXError' and 'Count' metrics, inspect Execution Logs for 'rate exceeded', and increase Usage Plan limits or request an AWS quota increase.
| Method | When to Use | Time | Risk |
|---|---|---|---|
| Increase Usage Plan Limits | API Key users are hitting legitimate throttling limits. | 5 mins | Low |
| Request Account Quota Increase | Overall account RPS exceeds 10,000 default limit. | 1-2 days | Low |
| Implement Client-Side Backoff | Handling expected burst traffic gracefully without dropping requests. | Hours | Medium |
| Enable API Caching | High read volume on static or slow-changing GET endpoints. | 15 mins | Medium |
Understanding the Error
When working with AWS API Gateway, one of the most common and disruptive issues developers face is hitting rate limits, resulting in an HTTP 429 Too Many Requests error. This is often accompanied by the default JSON payload {"message": "Too Many Requests"}. However, this is just one piece of the puzzle when managing API Gateway traffic. You might also encounter related errors such as HTTP 504 Gateway Timeout, HTTP 503 Service Unavailable, or even HTTP 404 Not Found if requests are misrouted during high load, throttling events, or deployments.
API Gateway employs several layers of throttling to protect your backend systems (like Lambda, ECS, or EC2) and AWS infrastructure from being overwhelmed. These include account-level limits, API-level limits, stage-level limits, method-level limits, and Usage Plan limits tied to specific API Keys. When a client exceeds any of these configured thresholds, API Gateway immediately rejects the request with a 429 status code before it ever reaches your backend code.
Understanding which layer is enforcing the rate limit is crucial for effective troubleshooting. A 429 error might indicate that a single tenant is abusing their pricing tier, or it could mean your entire AWS account is under a targeted DDoS attack.
Step 1: Diagnose the Root Cause
Before making arbitrary changes to configurations, you must pinpoint exactly what is being throttled and why. Blindly increasing limits can lead to backend overload, database crashes, and massive, unexpected cost spikes.
1. Check CloudWatch Metrics:
Navigate to the Amazon CloudWatch console and examine the AWS/ApiGateway namespace. Look for spikes in the 4XXError metric correlated with the overall Count metric. You should also analyze the IntegrationLatency and Latency metrics to see if backend slowdowns are causing clients to retry requests aggressively, thereby artificially inflating the request rate and triggering a throttling response.
2. Enable Detailed Execution Logging: If you haven't already, enable Execution Logs and Access Logs for your specific API Gateway stage. Execution logs provide granular details about the request lifecycle, including the exact moment and reason a request was rejected due to throttling.
Look for specific log entries such as:
Method request rate exceededMethod request quota exceededAPI Key rate exceeded
3. Analyze AWS WAF (if attached):
If you have an AWS WAF WebACL attached to your API Gateway, check the WAF metrics and sampled requests. A 429 error can also be generated by a WAF Rate-Based Rule rather than API Gateway's internal throttling. Look for spikes in the WAFBlock metric within the AWS/WAFV2 namespace.
Step 2: Fix Throttling and Rate Limits (429 Errors)
Depending on what your log analysis revealed, apply the appropriate fix from the scenarios below.
Scenario A: Usage Plan Limits Exceeded If a specific client is receiving 429 errors and you are enforcing API Keys, they have likely exceeded their assigned Usage Plan rate or quota.
- Navigate to the API Gateway console -> Usage Plans.
- Select the plan associated with the struggling API Key.
- Increase the Rate (requests per second) or Burst capacity under the Throttling tab to accommodate their legitimate traffic patterns.
- If they hit a monthly quota limit, increase the Quota threshold.
Scenario B: Account or Stage/Method Limits Exceeded If the entire API is throwing 429s across all users, you may have hit the default account limit (10,000 RPS / 5,000 burst) or a custom limit explicitly set on the Stage.
- Check Stage Settings: Go to your API -> Stages -> Settings tab. Ensure 'Default Method Throttling' is set to appropriate values (or disabled if you want to rely entirely on account-level limits).
- Request a Quota Increase: If your legitimate traffic exceeds the 10,000 RPS default, you must open a support ticket with AWS via the Service Quotas console to request an increase for the
API Gateway account-level rate limit.
Step 3: Fix Gateway Timeouts (504 Errors)
An aws api gateway timeout or HTTP 504 Gateway Timeout occurs when API Gateway does not receive a complete response from your backend integration within the maximum integration timeout period. The default and hard maximum for this timeout is 29 seconds.
1. Optimize Backend Performance: Identify why the backend is taking longer than 29 seconds. Is it a slow database query? Is a downstream third-party API timing out? You must profile and optimize the backend code to respond faster.
2. Handle Lambda Cold Starts: If your backend relies on AWS Lambda, cold starts—especially for functions attached to a VPC—can sometimes exceed the 29-second limit. Implement Provisioned Concurrency for your critical Lambda functions to keep instances warm and eliminate cold start latency.
3. Asynchronous Processing:
If the task inherently takes longer than 29 seconds (e.g., video processing, massive data exports, or complex AI generation), you must fundamentally change your API design. Instead of synchronous execution, the API Gateway should trigger an async process (e.g., putting a message on an SQS queue or starting a Step Functions execution) and return an HTTP 202 Accepted immediately. The client can then poll a status endpoint or wait for a webhook callback.
Step 4: Fix Service Unavailable (503) and Not Found (404)
Service Unavailable (503):
An aws api gateway service unavailable error usually signifies that the integration backend is completely down, rejecting connections, or experiencing extreme load.
- Check your Application Load Balancer (ALB) or Network Load Balancer (NLB) health checks if routing traffic to containers (ECS/EKS) or EC2 instances.
- Ensure your Lambda function hasn't hit its concurrent execution limit. While this typically causes Lambda to throttle with a 429, API Gateway might translate this to a 500 or 503 depending on your specific integration response mapping configurations.
Not Found (404):
An aws api gateway not found error, specifically accompanied by the payload {"message": "Missing Authentication Token"}, is a notoriously misleading error message. It almost always means the requested resource path or HTTP method does not exist in the currently deployed API Gateway stage, not that authentication actually failed.
- Verify the exact URL path and HTTP method (e.g., sending a GET request to a POST-only endpoint).
- Crucial check: Did you remember to deploy your API? Changes made in the API Gateway console's Resources tree are not active until you explicitly click Deploy API to a target stage.
- Check Custom Domain Name mappings. Ensure the Base Path Mapping correctly points the custom domain to your recently deployed Stage.
Frequently Asked Questions
# Use the AWS CLI to check current stage-level throttling settings
aws apigateway get-stage \
--rest-api-id <your-api-id> \
--stage-name <your-stage-name> \
--query 'methodSettings["*/*"].{RateLimit:throttlingRateLimit, BurstLimit:throttlingBurstLimit}'
# Update stage-level default throttling (e.g., set to 500 RPS, 1000 Burst)
aws apigateway update-stage \
--rest-api-id <your-api-id> \
--stage-name <your-stage-name> \
--patch-operations op=replace,path=/*/*/throttling/rateLimit,value=500 \
op=replace,path=/*/*/throttling/burstLimit,value=1000
# Query CloudWatch Logs Insights to find exact Throttling events in API Gateway Execution Logs
# Run this to pinpoint which endpoints or IPs are hitting the limits
aws logs start-query \
--log-group-name "API-Gateway-Execution-Logs_<api-id>/<stage-name>" \
--start-time $(date -v-1H +%s 2>/dev/null || date -d '1 hour ago' +%s) \
--end-time $(date +%s) \
--query-string "fields @timestamp, @message | filter @message like /rate exceeded/ | sort @timestamp desc | limit 20"Error Medic Editorial
Our editorial team consists of certified AWS Solutions Architects and Senior Site Reliability Engineers dedicated to providing practical, actionable infrastructure solutions for modern cloud environments.
Sources
- https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html
- https://aws.amazon.com/premiumsupport/knowledge-center/api-gateway-troubleshoot-429-errors/
- https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html
- https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/