AWS Throttle Fixer
AWS limits the number of requests across all APIs within an AWS account, per region. It also limits the burst across all APIs within an AWS account, per Region for some APIs. Due to this restriction many AWS APIs will trigger error responses like ThrottledException, TooManyRequestsException, Throttling and so on.
AWS Throttle Fixer internally uses Exponential backoff to remediate this issue and it is a promise based library. This library only works with aws-sdk version 2 and 3.
Table of Contents
Getting Started
How to install
The preferred way to install the AWS-Throttle-Fixer for Node.js is to use the npm package manager for Node.js. Simply type the following into a terminal window:
npm install aws-throttle-fixer
with yarn package manager
yarn add aws-throttle-fixer
Example
aws-sdk version 2.x.x
following example demonstrate calling a describeSnapshots operation with throttle fix enabled in aws-sdk v2.
// aws init
require('dotenv').config()
const AWS = require('aws-sdk')
let awsConfig = {
region: process.env.REGION,
accessKeyId: process.env.AWS_ACCESS_KEY_ID,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
}
AWS.config.update(awsConfig)
const ec2Client = new AWS.EC2()
// aws-throttle-fixer init
const ThrottleFixer = require('aws-throttle-fixer')
const TF = new ThrottleFixer()
const tfConfig = {
retryCount: 24,
logger: console.log,
sdkVersion: 2,
exceptionCodes: ['RequestLimitExceeded'],
}
TF.configure(tfConfig)
const throttleFixFn = TF.throttleFixer()
// aws call is in the function
async function callAwsDescribeSnapshotsAction() {
try {
const params = { MaxResults: 10 }
const snapshotDetails = await throttleFixFn(ec2Client, 'describeSnapshots', params) // calling describeSnapshots operation with throttle fix added
return snapshotDetails
} catch (e) {
console.error(e)
}
}
callAwsDescribeSnapshotsAction().then()@aws-sdk version 3.x.x
following example demonstrate calling a describeSnapshots operation with throttle fix enabled in aws-sdk v3.
// aws init
require('dotenv').config()
const { EC2Client, DescribeSnapshotsCommand } = require('@aws-sdk/client-ec2')
const client = new EC2Client({ region: 'us-east-1' })
// aws-throttle-fixer init
const ThrottleFixer = require('aws-throttle-fixer')
const TF = new ThrottleFixer()
const tfConfig = {
retryCount: 24,
logger: console.log,
sdkVersion: 3,
exceptionCodes: ['RequestLimitExceeded'],
}
TF.configure(tfConfig)
const throttleFixFn = TF.throttleFixer()
// aws call is in the function
async function callAwsDescribeSnapshotsAction() {
try {
const params = { MaxResults: 10 }
const { Snapshots } = await throttleFixFunction(client, DescribeSnapshotsCommand, params)
} catch (e) {
console.error(e)
}
}
callAwsDescribeSnapshotsAction().then()Usage
In Node.js
To use the AWS-Throttle-Fixer within your nodejs project, import aws-throttle-fixer as you normally would.
ES5 imports
const ThrottleFixer = require('aws-throttle-fixer')Create the Throttle fixer instance
const TF = new ThrottleFixer()Configure the options
TF.configure({ retryCount: 24 }) // more available options are listed [here](#configure)Create a callable throttle method
const throttleFixFn = TF.throttleFixer()throttleFunction takes 3 arguments. All are required and arguments are different for different sdk version
With sdk version 2
| Sl.no | Argument | Description | Type | Example |
|---|---|---|---|---|
| 1 | AWS Client/Class | The aws class initialed using aws-sdk
|
class |
EC2 |
| 2 | Method | The method or action from the class | string |
describeSnapshots |
| 3 | Parameters | Parameter to pass to the AWS method | object |
{ MaxResults: 10 } |
With sdk version 3
| Sl.no | Argument | Description | Type | Example |
|---|---|---|---|---|
| 1 | AWS Client/Class | The aws class initialed using aws-sdk
|
class |
EC2 |
| 2 | Command | The Command imported from sdk | function |
DescribeSnapshotsCommand |
| 3 | Parameters | Parameter to pass to the AWS method | object |
{ MaxResults: 10 } |
Call throttleFixFn function with all arguments provided
const response = await throttleFixFn(awsClient, 'awsService', params) // for sdk version 2
const response = await throttleFixFn(awsClient, CommandFromClient, params) // for sdk version 3Configurations
| API Name | Description | Type | Default |
|---|---|---|---|
retryCount |
Number of retries to perform in case of throttle error | number |
10 |
logger |
A function that can be used for logging the debug logs about throttling | function |
null |
exceptionCodes |
What all error codes need to be considered as Throttled? by default following error codes are considered to be throttling ThrottledException, TooManyRequestsException, Throttling
|
string[] |
[] |
ignoreRetryState |
If set to true, will ignore the retry state retryable in aws api response. Available only when using sdkVersion with value 2 |
boolean |
false |
sdkVersion |
AWS SDK version number, provide only major version | number |
2 |
additionalWaitTime |
API will wait for the specified time before making any other actions, (time in milliseconds) | number |
0 |
Error Codes
-
UnknownClientException- this exception will raise if no aws client is provided to thethrottleFixFnfunction -
UnknownModuleException- this exception will raise if no module name is provided to thethrottleFixFnfunction (only when usingsdkVersion2) -
UnknownSdkVersionException- this exception will raise ifsdkVersionprovided to the configuration is incorrect -
UnknownCommandException- this exception will raise ifcommandprovided to thethrottleFixFnconfiguration is incorrect (only when usingsdkVersion3) - others - All other errors are thrown from the method
