API throttling limits
Throttling is the process of limiting the number of requests you (or your authorized developer) can submit to a given operation in a given amount of time. Throttling protects the web service from being overwhelmed with requests and ensures all authorized developers have access to the web service. Requests that have been throttled will return a 429 HTTP status code, see error handling for information on how to handle throttled requests.
The Leaky Bucket Algorithm
This algorithm is based on the analogy where a bucket has a hole in the bottom from which water leaks out at a constant rate. Water can be added to the bucket intermittently, but if too much water is added at once or if water is added at too high an average rate, the water will exceed the capacity of the bucket.
To apply this analogy here, imagine that the bucket represents the maximum request quota, which is the maximum number of requests you can make at one time. The hole in the bucket represents the restore rate, which is the amount of time it takes to be able to make new requests. So, if you submit too many requests at once, then the bucket overflows and, throttling occurs. If you fill up the bucket, it takes some time before you can add more water to the bucket since the water leaks from the bucket at a steady rate. So the ability to submit more requests after you have reached the maximum request quota is governed by the restore rate, the time it takes to allow you to make new requests.
Key terms
- Request quota - The number of requests that you can submit at one time without throttling. The request quota decreases with each request you submit, and increases at the restore rate (measured in seconds). Requests are calculated for each Amazon seller account and Amazon MWS developer account pair.
- Max quota (also called the burst rate) - The maximum size that the request quota can reach.
- Restore rate (also called the recovery rate) - The rate at which your request quota increases over time measured in seconds, up to the maximum request quota.
To apply these ideas, consider this example. Imagine that you want to use the CreateCharge operation to submit 30 create charge requests. The CreateCharge operation has a request quota of 10 and a restore rate of one new request every 4 seconds. If you submit all 30 create charge requests at once, your requests will be throttled after 20 requests. You would then have to resubmit 10 requests once the request quota had been restored. Since the restore rate is one request every 4 seconds, it would take 40 seconds for you to be able to submit the remaining 10 requests. So, instead of submitting all the requests and having to resubmit the requests that were throttled, you could automate your process to submit requests incrementally.
For example, you could submit 10 requests (out of your original 30 requests), and the request quota would still have 10 requests left over. You could then wait 1 minute, and the restore rate would have increased the request quota to 25 (one request every 4 seconds for 60 seconds gives you 15 new requests). You could then submit 10 more requests. For the remaining 15 createCharge requests, you could wait more time then submit them or submit more requests since your quota is higher now.
This table indicates that the maximum number of requests that can be made before getting throttled are “burst” number and the quota is restored at a rate of 1 request per “restore” seconds.
| API
|
Live
|
Sandbox
|
||
|
|
Burst
|
Restore (s)
|
Burst
|
Restore (s)
|
| Cancel Charge
|
10
|
2
|
2
|
1
|
| Capture Charge
|
20
|
4
|
2
|
1
|
| Close Charge Permission
|
10
|
2
|
2
|
1
|
| Complete Checkout Session
|
20
|
4
|
2
|
1
|
| Create Charge
|
10
|
4
|
2
|
1
|
| Create Checkout Session
|
40
|
16
|
5
|
1
|
| Create Merchant Account
|
10
|
1
|
1
|
1
|
| Create Refund
|
10
|
4
|
2
|
1
|
| Create Delivery Tracker
|
10
|
1
|
1
|
1
|
| Get Authorization Token
|
5
|
1
|
N/A
|
N/A
|
| Get Charge
|
20
|
4
|
5
|
1
|
| Get Charge Permission
|
20
|
4
|
10
|
1
|
| Get Checkout Session
|
40
|
8
|
10
|
1
|
| Get Merchant Status
|
10
|
1
|
1
|
1
|
| Get Refund
|
20
|
4
|
5
|
1
|
| Update Charge Permission
|
10
|
2
|
5
|
1
|
| Update Checkout Session
|
20
|
8
|
5
|
1
|
| API
|
Live
|
Sandbox
|
||
|
|
Burst
|
Restore (s)
|
Burst
|
Restore (s)
|
| Cancel Charge
|
10
|
2
|
2
|
1
|
| Capture Charge
|
20
|
4
|
2
|
1
|
| Close Charge Permission
|
10
|
2
|
2
|
1
|
| Complete Checkout Session
|
20
|
4
|
2
|
1
|
| Create Charge
|
10
|
4
|
2
|
1
|
| Create Checkout Session
|
40
|
16
|
2
|
1
|
| Create Refund
|
10
|
4
|
2
|
1
|
| Create Delivery Tracker
|
10
|
1
|
1
|
1
|
| Get Authorization Token
|
5
|
1
|
N/A
|
N/A
|
| Get Charge
|
20
|
4
|
5
|
1
|
| Get Charge Permission
|
20
|
4
|
5
|
1
|
| Get Checkout Session
|
40
|
8
|
5
|
1
|
| Get Refund
|
20
|
4
|
5
|
1
|
| Update Charge Permission
|
10
|
2
|
2
|
1
|
| Update Checkout Session
|
20
|
8
|
2
|
1
|
| API
|
Live
|
Sandbox
|
||
|
|
Burst
|
Restore (s)
|
Burst
|
Restore (s)
|
| Cancel Charge
|
10
|
2
|
2
|
1
|
| Capture Charge
|
20
|
4
|
2
|
1
|
| Close Charge Permission
|
10
|
2
|
2
|
1
|
| Complete Checkout Session
|
20
|
4
|
2
|
1
|
| Create Charge
|
10
|
4
|
2
|
1
|
| Create Checkout Session
|
40
|
16
|
2
|
1
|
| Create Merchant Account
|
10
|
1
|
1
|
1
|
| Create Refund
|
10
|
4
|
2
|
1
|
| Create Delivery Tracker
|
10
|
1
|
1
|
1
|
| Get Authorization Token
|
5
|
1
|
N/A
|
N/A
|
| Get Charge
|
20
|
4
|
5
|
1
|
| Get Charge Permission
|
20
|
4
|
5
|
1
|
| Get Checkout Session
|
40
|
8
|
5
|
1
|
| Get Merchant Status
|
10
|
1
|
1
|
1
|
| Get Refund
|
20
|
4
|
5
|
1
|
| Update Charge Permission
|
10
|
2
|
2
|
1
|
| Update Checkout Session
|
20
|
8
|
2
|
1
|
Tips on avoiding throttling
There are several things you can do to make sure your requests and submissions are processed successfully:
- Know the throttling limit of the specific request you are submitting.
- Have a "back off" plan for automatically reducing the number of requests if the service is unavailable. The plan should use the restore rate value to determine when a request should be resubmitted.
You should also distribute your requests to maximize service availability:
- Submit requests at times other than on the hour or on the half hour. For example, submit requests at 11 minutes after the hour or at 41 minutes after the hour.
- Take advantage of times during the day when traffic is likely to be low, such as early evening or early morning hours.