The Willow API implements rate limiting to ensure fair usage and maintain service reliability for all users. Rate limits are applied on a per-client basis and help protect the platform from excessive load.
The following endpoints have rate limits applied:
| Endpoint Pattern | Request Limit | Time Window |
|---|---|---|
/v3/time-series/* | 20 requests | 10 seconds |
/v3/twins/* | 20 requests | 10 seconds |
Rate limits use a Fixed Window algorithm, meaning the request count resets at the end of each 10-second interval.
When a rate limit is exceeded, the API will return an error response with a 429 HTTP Response Code. The response body will include a message indicating which endpoint was affected and suggestions for reducing API calls.
Example response when the time-series rate limit is exceeded:
Rate limit exceeded for time-series endpoint. Consider using bulk queries to reduce API calls.Example response when the twins rate limit is exceeded:
Rate limit exceeded for twins endpoint. Consider using bulk twin queries to reduce API calls.To avoid hitting rate limits, consider the following strategies:
- Use bulk queries: Both the Time Series and Twins endpoints support batch operations. Combine multiple items into a single request where possible.
- Implement request throttling: Add delays between requests in your application to stay within the rate limit.
- Cache responses: Store frequently accessed data locally to reduce the number of API calls.
- Handle rate limit errors gracefully: Implement retry logic with exponential backoff when you receive a rate limit response.