ThrottlingException
This error occurs when an API client is rate-limited or throttled by an AWS service due to exceeding transactional throughput limits.
Usually happens because:
- ☑ DynamoDB transactional throughput exceeds provisioned RCU/WCU limits
- ☑ AWS Lambda function hits reserved or regional concurrency allocations limits
- ☑ High concurrent cryptographic operations exceed regional KMS rate limits
🔍 Quick Checklist:
What is ThrottlingException?
A 'ThrottlingException' is a rate-limiting error thrown by modern AWS services (like API Gateway, Lambda, DynamoDB, or KMS) when client request rates exceed allocated transactional throughput thresholds. Unlike RequestLimitExceeded (which typically targets control plane APIs like EC2), ThrottlingException applies to data plane and application-level APIs. AWS services utilize Token Bucket rate limiting; when client calls exceed bucket capacity, subsequent requests are dropped with this exception.
Common Causes
- DynamoDB Provisioned Capacity Exhaustion: Write/read throughput exceeds the table's provisioned Read/Write Capacity Units (RCUs/WCUs).
- AWS Lambda Concurrent Executions Limit: The account-level or function-reserved concurrency limit has been reached, causing Lambda to reject new invocations.
- KMS Cryptographic Operation Throttling: High-volume cryptographic calls (kms:Encrypt/Decrypt) exceed default regional request limits.
| Cause | Frequency |
|---|---|
| DynamoDB read/write operations exceed configured WCU/RCU limits | ⭐⭐⭐⭐⭐ |
| KMS decryption requests exceed regional cryptographic API rates | ⭐⭐⭐⭐ |
| AWS Lambda concurrent executions hit reserved concurrency limits | ⭐⭐⭐ |
Common Mistakes
- Using static provisioned capacity mode on database workloads that experience highly erratic traffic spikes, triggering constant throttling.
- Neglecting to configure buffer queues (like Amazon SQS) in front of slow-starting Lambda functions.
How to Fix
AWS Operations & Verification
Configure the AWS configuration file to enforce adaptive client-side rate-limiting behaviors.
[default]
region = us-east-1
# Enforce adaptive mode to dynamically slow client request rates
retry_mode = adaptive
max_attempts = 15Platform Specific Fixes
Check active lambda concurrent executions limits using AWS CLI commands.
# 1. Inspect regional lambda concurrency settings
aws lambda get-account-settings
# 2. Check a specific function's reserved concurrency
aws lambda get-function-concurrency --function-name process-ordersBest Practices
- Enable Amazon DynamoDB Auto Scaling to dynamically adapt capacity limits to active workload traffic.
- Implement client-side request queues or caching architectures to flatten traffic spikes.
Frequently Asked Questions (FAQ)
Q: What is a ThrottlingException in AWS?
This is a data-plane rate-limiting error. It means your application is making calls (like database writes, lambda invocations, or key decrypts) faster than the configured capacity or regional limits allow.
Q: How does DynamoDB handle throttling?
If your database transactions exceed the provisioned Read/Write Capacity Units, DynamoDB returns a ThrottlingException. To avoid this, you can switch the table billing mode to 'PAY_PER_REQUEST' (On-Demand) or enable Auto Scaling to scale capacity dynamically.
Q: Why does KMS throttling occur?
AWS KMS enforces regional limits on cryptographic calls (typically ranging from 10,000 to 80,000 requests per second depending on the region). If your application decrypts thousands of objects concurrently, KMS throttles the calls. You can request a quota increase or implement caching (e.g. AWS SDK KMS cache) to reduce API load.
Q: What is the adaptive retry mode in AWS SDKs?
Standard retry mode uses a fixed backoff. Adaptive retry mode dynamically measures throttle responses from AWS and client-side delays outgoing calls before they are sent, matching client traffic to the service's current throughput capacity.