Rate Limiting

The Canopy API employs rate limiting as a method to ensure high availability and stability for all customers.

Canopy API users that send too many requests within specific time windows may see their requests fail with the HTTP status code 429.

Rate Limits

For most endpoints, the Canopy API allows up to 25 read operations per second and up to 5 write operations per second. Rate limits are per organization and operate on a rolling window.

Tasking Umbra satellites is a time-consuming operation. For that reason, a few endpoints have far lower rate limits:

📘

If the Canopy API is under increased load, it may take more than a few minutes for Task and Feasibility status transitions to occur. When this happens, consider reducing your polling rate for updates. If status transitions are delayed for more than an hour, contact your Canopy representative.

Archive Catalog Rate Limits

The Umbra Archive Catalog (all endpoints under /archive) in the Canopy API is rate limited a bit differently.

Requests to these endpoints are rate limited to 2 Requests / Second by request IP Address.

Tips for Handling Rate Limited Requests Effectively

When developing your applications, develop them in such a way that they gracefully handle 429 status codes.

For most of the Canopy API endpoints, Umbra recommends retrying on failure using exponential back off plus some random "jitter" so the thundering herd problem is avoided. The rate limits documented here may change at any time, so avoid referencing any specific limit.

For the Canopy API endpoints with low rate limits, such as creating new Tasks or Feasibilities, Umbra recommends handling rate limiting client-side if the 429 code is encountered too often. This allows clients to queue Task and Feasibility requests inject logic that, for example, skips a request if the Task window has passed.