We apply rate limits to all endpoints, including the token endpoint, to protect the Understory API against erroneous applications. Limits cover both the number of concurrent requests and the number of requests within a time window. We adjust them as needed, so do not build your integration around a specific number.
If you reach a limit you receive an HTTP status 429 Too Many Requests. Do not retry immediately. Back off for at least one minute, and increase the wait if the next attempt is limited too.
The body of a 429 response may not follow the standard error format, so rely on the status code rather than the body.
- Reuse your access token until it is about to expire. Requesting a token per API call doubles your request count. See Access tokens.
- Use webhooks instead of polling to find out what changed. See Webhooks.
- Page with large pages where the endpoint allows it, rather than many small ones. See Pagination.
- Spread out bulk work, such as a nightly export, instead of sending every request at once.