Handle API Throttling
The Alexa Smart Properties (ASP) REST APIs limit the number of Transactions per Second (TPS) or requests per second that they can handle. Your code should account for this by properly handling HTTP 429 Request Throttled responses.
How to handle API throttling in your code
When a request to an API exceeds the TPS limit for that API, the API returns an HTTP 429 Request Throttled response. A throttled response is a valid state for the API and shouldn't be regarded as an error.
Amazon recommends that you code defensively and handle the throttled response gracefully. Your code to handle 429 responses and retry API calls shouldn't depend on the specific TPS limit for a particular API. Good code can ignore the TPS limits and use the same algorithm across all the ASP APIs.
For example, manage requests that return a 429 as follows:
- Use a try/catch structure to retry the request and catch errors. Handle other errors appropriately, such as with notifications or throwing exceptions upstream.
- If the response code indicates a successful call (usually 200 or 202), use the response normally.
- If the response code is 429, retry after waiting for a sleep period and increment the retry count.
- Increment your sleep period by doubling it every retry
- Have a maximum number of retries and stop retires after this max retry count
Sample code to handle 429 responses
The following code example shows a request manager function (getAPIResponse) that implements retry code.
import axios from 'axios';
export const apiSettings =
{
apiDelay : 1000,
baseURL : 'https://api.amazonalexa.com',
backoff: "2000,3000,5000,8000,13000,21000"
}
function apiCallDelay(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
let backoff;
//config is an axios config object
export async function getAPIResponse(config, backoffIndex) {
if (backoffIndex === undefined && apiSettings.backoff.length > 0) {
backoff = apiSettings.backoff.split(',');
backoffIndex = 0;
}
let res = null;
try {
res = await axios(config);
await apiCallDelay(apiSettings.apiDelay);
if (res.data) {
return res.data;
}
return{statuscode: res.status};
} catch (err) {
if (err.response?.status)
{
//429 TOO_MANY_REQUESTS
if ([503,500,429].includes(err.response.status)) {
if (backoffIndex < backoff.length) {
await apiCallDelay(backoff[backoffIndex]);
return getAPIResponse(config, backoffIndex + 1);
}
}
res = err.response.data;
res.statuscode = err.response.status;
} else if (err.response && (typeof err.response.data) === 'string') {
// api does not return json data
res = { statuscode : err.response.status};
}
else
{
res = { code : err.code};
}
return res;
}
}
TPS limits for the ASP REST APIs
The table in this section summarizes the TPS limits for the ASP REST APIs. These details are provided to help set expectations for API behavior. However, as noted earlier, don't rely on these specific limits or reference them in code.
The table refers to the following concepts:
- Shared TPS – The number of transactions per second is shared across all customers that call that API operation at the same time. For example, assume the shared TPS of an API is 10. When one customer calls the API at five TPS, there is only five more TPS available for other customers.
-
Shared across operations – Some APIs share the TPS across a suite of API operations instead of each individual operation. For example, the TPS limit for reminders is applied against the sum of
POST /v2/alerts/reminders,GET /v2/alerts/reminders/{reminderId},PUT /v2/alerts/reminders/{reminderId}, andDELETE /v2/alerts/reminders/{reminderId}.The Notes column indicates whether an API operation shares TPS across other operations.
-
Limits that depend on configuration – Some APIs have a TPS limit that depends on the parameters of the API or the configuration of the property. For example, the /
v1/addressBooks/{addressBookId}/contactscall to create or delete contacts in address books has a TPS limit divided by the number of units associated with the address book. If an address book is associated with 20 rooms, the TPS limit for adding or deleting a contact in this address book is 15/20 = 0.75.The Notes column describes the configuration details that can change the TPS for a given API operation.
| API operation | Units per API request | NA TPS limit | Shared TPS | Notes |
|---|---|---|---|---|
|
Analytics API | ||||
|
|
0.33 |
10 |
No |
3 requests for every 15 minutes |
|
|
1.0 |
10 |
Yes | |
|
Get all certificate authorities
|
1.0 |
20 |
Yes | |
|
Get all certificate authorities (expand all)
|
1.0 |
10 |
Yes | |
|
Get certificate authority details
|
1.0 |
50 |
Yes | |
|
Get certificate authority details (expand all)
|
1.0 |
10 |
Yes | |
|
Communications API | ||||
|
Create a communication profile
|
1 |
20 |
No |
Global limit of 20 TPS across all clients |
|
|
1 |
10 |
No |
Global limit of 100 TPS across all clients. TPS for operations on address books are divided by the number of units currently associated with the address book. If an address book is currently associated with 20 rooms, the TPS limit for adding or deleting a contact in this address book is 10/20 = 0.50. |
|
Create a reciprocal association
|
1 |
20 |
No |
Global limit of 20 TPS |
|
Create address book associations in bulk
|
100.0 |
2 |
Yes | |
|
Create address book associations in bulk
|
100 |
2 |
Yes | |
|
|
1 |
40 |
No |
Global limit of 100 TPS across all clients |
|
Create an address book association
|
1 |
10 |
No | |
|
|
1 |
5 |
No | |
|
Create communication profiles in bulk
|
100.0 |
2 |
Yes | |
|
|
100.0 |
2 |
Yes | |
|
|
100 |
2 |
Yes | |
|
Delete a communication profile
|
1 |
20 |
No |
Global limit of 20 TPS across all clients |
|
|
1 |
10 |
No |
Global limit of 15 TPS across all clients |
|
Delete a reciprocal association status
|
1 |
20 |
No |
Global limit of 20 TPS |
|
|
1 |
40 |
No |
Global limit of 100 TPS across all clients |
|
Delete an address book association
|
1 |
10 |
No | |
|
Get a communication profile by entity id
|
1 |
20 |
No |
Global limit of 20 TPS across all clients |
|
Get a communication profile by profileId
|
1 |
20 |
No |
Global limit of 20 TPS across all clients |
|
|
1 |
30 |
No |
Global limit of 15 TPS across all clients |
|
|
1 |
40 |
No |
Global limit of 100 TPS across all clients |
|
Get an address book association
|
1 |
10 |
No | |
|
|
1 |
5 |
No | |
|
|
1 |
5 |
No | |
|
Get reciprocal association status
|
1 |
20 |
No |
Global limit of 20 TPS |
|
List address book associations for a unit
|
1 |
10 |
No | |
|
|
1 |
40 |
No |
Global limit of 100 TPS across all clients |
|
|
1 |
10 |
No |
Global limit of 15 TPS across all clients |
|
|
1 |
5 |
No | |
|
|
1 |
10 |
No |
Global limit of 15 TPS across all clients |
|
|
1 |
40 |
No |
Global limit of 100 TPS across all clients |
|
Endpoint Features API | ||||
|
All operations with a URI that begins with: |
1.0 |
50 |
No | |
|
All operations with a URI that begins with: |
1.0 |
50 |
No | |
|
|
1.0 |
100 |
No | |
|
|
1.0 |
100 |
Yes |
After 20 TPS, requests take longer to complete. |
|
Endpoints API | ||||
|
All operations with a URI that begins with: |
1.0 |
100 |
No | |
|
|
1.0 |
15 |
No | |
|
|
1.0 |
50 |
No | |
|
|
1.0 |
15 |
No | |
|
|
1.0 |
50 |
No | |
|
Event Messenger API | ||||
|
|
1.0 |
10 |
No | |
|
Create a subscription configuration
|
1.0 |
10 |
No | |
|
Delete a subscription configuration
|
1.0 |
10 |
No | |
|
|
1.0 |
10 |
No | |
|
|
1.0 |
30 |
No | |
|
Get a subscription configuration by ID
|
1.0 |
30 |
No | |
|
Get subscription configurations
|
1.0 |
30 |
No | |
|
|
1.0 |
30 |
No | |
|
Notifications API | ||||
|
|
100.0 |
3 |
No |
TPS increases if the number of units decreases. You can create notifications for 300 units per second. |
|
Proactive Suggestion API | ||||
|
|
100.0 |
3 |
No |
TPS increases if the number of units decreases. You can create notifications for 300 units per second. |
|
Property Hierarchy Management API | ||||
|
|
1.0 |
30 |
Yes | |
|
Reminders API | ||||
|
|
1.0 |
10 |
Yes |
All reminder APIs have one shared pool of TPS which is in total 50 TPS |
|
|
1.0 |
10 |
Yes |
All reminder APIs have one shared pool of TPS which is in total 50 TPS |
|
|
1.0 |
10 |
Yes |
All reminder APIs have one shared pool of TPS which is in total 50 TPS |
|
|
1.0 |
10 |
Yes |
All reminder APIs have one shared pool of TPS which is in total 50 TPS |
|
Skill Management API | ||||
|
Enable a skill for multiple units
|
100 |
2 |
No |
Related topics
Last updated: frontmatter-missing