# Rate Limiting

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.

## Rate Limit Configuration

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.

## Handling Rate Limit Responses

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.
```

## Best Practices

To avoid hitting rate limits, consider the following strategies:

- **Use bulk queries**: Both the [Time Series](/docs/resource-guide-time-series) and [Twins](/docs/resource-guide-digital-twin) 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.


div
If your application consistently requires higher throughput, please contact developer support to discuss your use case.