Skip to main content

Rate limits

Canary applies a one-minute request budget per API key. Separate keys have separate budgets.

Successful response headers

Rate limit headers appear on successful authenticated responses:
X-RateLimit-Reset is a Unix timestamp in seconds. Authentication, validation, and other error responses may omit these three headers, so clients should treat them as optional.

Handle 429

A depleted budget returns 429 Too Many Requests with Retry-After in seconds:
Honor Retry-After, add a small random delay, and retry within a bounded attempt count.

Stay within the budget

  • Request the largest useful page size: up to 100 for native lists and 200 for work requests or portals.
  • Cache slow-changing records such as locations and custom-field definitions.
  • Process changes in a queue with bounded concurrency.
  • Use X-RateLimit-Remaining as an early signal when the header is present.
  • Use one key per independent workload so ownership and budget usage stay observable.
For sustained workloads near the published limit, contact support@oncanary.com with the organization, use case, expected volume, and visible key prefix.