Rate Limits and Throttling in the Cano Analytics API

Cano enforces rate limits to ensure fair usage and platform stability across all customers — understanding them helps you design resilient integrations that degrade gracefully under load rather than failing hard. Limits are applied per API key and reset on a rolling window basis.

Limits by Endpoint Group

Different endpoint groups have different limits reflecting their relative cost to the platform. High-volume event ingestion supports far higher throughput than administrative actions.

Endpoint Group	Requests / sec	Requests / min
Event ingestion (`POST /v1/events`)	1,000	50,000
User identify (`POST /v1/identify`)	500	25,000
Query / Dashboards	100	3,000
Admin (workspace, team, billing)	10	300

Customers on the Pro and Enterprise plans receive significantly higher rate limits. Enterprise plans also support custom limits tailored to your ingestion volume. Reach out to your account manager or visit Settings → Billing to upgrade.

Rate Limit Headers

Every API response — including successful ones — includes three headers that tell you exactly where you stand within the current window. Read these headers to implement proactive throttling before you hit a 429.

Header	Description
`X-RateLimit-Limit`	Your total request allowance for the current window
`X-RateLimit-Remaining`	How many requests you have left in the current window
`X-RateLimit-Reset`	Unix timestamp (seconds) when the current window resets and your allowance refills

A typical response header set looks like this:

X-RateLimit-Limit: 50000
X-RateLimit-Remaining: 49812
X-RateLimit-Reset: 1730470860

Handling 429 Errors

When you exceed a rate limit, the API returns an HTTP 429 Too Many Requests response. The X-RateLimit-Reset header tells you exactly when you can retry, but the most robust strategy is exponential backoff with jitter — each successive retry waits longer, and a small random offset prevents synchronized retry storms when multiple clients hit the limit simultaneously.

Retry with Exponential Backoff

async function trackWithRetry(payload, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch("https://api.canoanalytics.io/v1/events", {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    });

    if (res.status !== 429) return res;

    const delay = Math.pow(2, i) * 100 + Math.random() * 50;
    await new Promise((resolve) => setTimeout(resolve, delay));
  }

  throw new Error("Exceeded maximum retries due to rate limiting.");
}

// Usage
await trackWithRetry({ event: "page_viewed", user_id: "usr_123", properties: { page: "/pricing" } });

This gives you wait times of roughly 100 ms → 200 ms → 400 ms across three attempts, with up to 50 ms of random jitter applied each time. Adjust the base multiplier and retry count to match the criticality of your workload.

Use the batch events endpoint (POST /v1/events/batch) to send up to 500 events in a single request. Batching is the single most effective way to reduce your request count — it cuts API calls by orders of magnitude for high-volume producers without sacrificing delivery guarantees.

Best Practices

Monitor remaining headroom proactively

Read X-RateLimit-Remaining on every response and begin throttling your outbound request rate when it drops below 10–15% of X-RateLimit-Limit. This prevents hitting the wall entirely and keeps your integration running smoothly during traffic spikes.

Use test keys during load testing

Rate limits apply per API key. Use a cano_test_sk_... key in your staging and load-testing environments so test traffic does not consume production quota.

Distribute load across multiple keys

If your architecture runs multiple independent services, give each one its own API key. Each key receives its own rate limit allowance, so you effectively multiply your total throughput capacity.

Overview

Endpoints

SDKs

Rate Limits and Throttling in the Cano Analytics API

Limits by Endpoint Group

Rate Limit Headers

Handling 429 Errors

Best Practices

​Limits by Endpoint Group

​Rate Limit Headers

​Handling 429 Errors

​Best Practices

Limits by Endpoint Group

Rate Limit Headers

Handling 429 Errors

Best Practices