How to Throttle API Gateway Requests in AWS

To throttle requests in AWS API Gateway, configure the throttling settings in a usage plan or directly on the API stage. This limits the number of requests per second and burst capacity, helping protect your backend from overload.

Syntax

Throttling in API Gateway is set using rate and burst limits within a usage plan or stage settings.

• rateLimit: The steady-state requests per second allowed.
• burstLimit: The maximum number of requests allowed in a short burst.

These settings can be applied via AWS Console, AWS CLI, or Infrastructure as Code tools like AWS CloudFormation or Terraform.

yaml

UsagePlan:
  Type: AWS::ApiGateway::UsagePlan
  Properties:
    UsagePlanName: ExampleUsagePlan
    Throttle:
      RateLimit: 100
      BurstLimit: 200
    ApiStages:
      - ApiId: !Ref ApiGatewayRestApi
        Stage: prod

Example

This example shows how to create a usage plan with throttling limits of 50 requests per second and a burst limit of 100 using AWS CLI commands.

bash

aws apigateway create-usage-plan \
  --name "BasicUsagePlan" \
  --throttle rateLimit=50,burstLimit=100 \
  --api-stages apiId=your-api-id,stage=prod

Output

{
  "id": "a1b2c3d4",
  "name": "BasicUsagePlan",
  "throttle": {
    "rateLimit": 50,
    "burstLimit": 100
  },
  "apiStages": [
    {
      "apiId": "your-api-id",
      "stage": "prod"
    }
  ]
}

Common Pitfalls

Common mistakes when throttling API Gateway include:

• Setting rateLimit too low, causing legitimate traffic to be blocked.
• Not associating the usage plan with API keys, so throttling does not apply.
• Confusing burstLimit with rateLimit and setting them incorrectly.
• Forgetting to deploy the API stage after changing throttling settings.

bash

Wrong example (no usage plan association):
aws apigateway update-stage \
  --rest-api-id your-api-id \
  --stage-name prod \
  --patch-operations op=replace,path=/throttling/rateLimit,value=100

Right example (using usage plan):
aws apigateway create-usage-plan --name "Plan" --throttle rateLimit=100,burstLimit=200
aws apigateway create-usage-plan-key --usage-plan-id plan-id --key-type API_KEY --key-id api-key-id

Quick Reference

Summary tips for throttling API Gateway:

• Use rateLimit to control steady request rate.
• Use burstLimit to allow short spikes.
• Apply throttling via usage plans linked to API keys.
• Deploy API stage after changes.
• Monitor usage with CloudWatch metrics.

Key Takeaways

Set throttling limits using rateLimit and burstLimit in usage plans or stage settings.

Associate usage plans with API keys to enforce throttling per client.

Deploy API stages after updating throttling settings to apply changes.

Monitor API usage with CloudWatch to adjust throttling as needed.

Avoid setting limits too low to prevent blocking valid traffic.