Rate limits and usage

The two limits

The per-minute rate limit

Counted per key and per account in a fixed one-minute window. Three headers on every authenticated response tell you where you stand, so you never have to guess.

HTTP/1.1 200 OK
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 1893506460

HTTP/1.1 429 Too Many Requests
Retry-After: 18

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 18 seconds."
  },
  "request_id": "7b82b7f7-4d13-497b-9f20-58d46fd7a510"
}

A fixed window means the counter resets on a boundary rather than sliding. In practice that means bursting immediately after a reset is fine, and bursting across a boundary can use two windows' worth of budget in quick succession without tripping anything.

Handling a 429

Retry-After is authoritative. Honour it rather than computing your own backoff — a client that guesses tends to guess low and get limited again.

async function callWithRateLimitHandling(path, options, attempt = 0) {
  const response = await fetch(BASE + path, options);

  if (response.status === 429) {
    const payload = await response.json();

    // The two 429s mean very different things.
    if (payload.error.code === "quota_exhausted") {
      throw new QuotaError(payload.error.details);   // waiting will not help
    }

    if (attempt >= 3) throw new Error("Rate limited after 3 retries");

    // Retry-After is authoritative. Do not guess.
    const wait = Number(response.headers.get("Retry-After") ?? 1);
    await sleep(wait * 1000);

    return callWithRateLimitHandling(path, options, attempt + 1);
  }

  return response;
}

The early check for quota_exhausted is the important line. Without it, a retry loop that treats every 429 the same will keep retrying an allowance that cannot refill until the month turns over.

Pacing before you are limited

Better than reacting to a 429 is not causing one. Because every response carries the remaining count, a client can slow itself down as it approaches the boundary.

// Slow down before you are told to, not after.
let remaining = Infinity;
let resetAt = 0;

async function paced(path, options) {
  if (remaining < 10) {
    const wait = Math.max(0, resetAt * 1000 - Date.now());
    await sleep(wait);
  }

  const response = await fetch(BASE + path, options);

  remaining = Number(response.headers.get("RateLimit-Remaining") ?? Infinity);
  resetAt = Number(response.headers.get("RateLimit-Reset") ?? 0);

  return response;
}

Where limits are usually hit

Reading your usage

GET /usage reports the current billing cycle and every metered metric. It is cheap, creates nothing, and is the right way to check headroom before a bulk job rather than discovering the ceiling halfway through one.

GET /usage

{
  "data": {
    "environment": "production",
    "cycle": {
      "id": "3f9d6a2c-...",
      "starts_at": "2030-01-01T00:00:00.000Z",
      "resets_at": "2030-02-01T00:00:00.000Z"
    },
    "metrics": [
      {
        "metric": "new_timers",
        "total": 214,
        "limit": 1000,
        "remaining": 786,
        "warning_threshold": 0,
        "starts_at": "2030-01-01T00:00:00.000Z",
        "resets_at": "2030-02-01T00:00:00.000Z"
      },
      {
        "metric": "api_requests",
        "total": 48213,
        "limit": "unlimited",
        "remaining": "unlimited",
        "warning_threshold": 0,
        "starts_at": "2030-01-01T00:00:00.000Z",
        "resets_at": "2030-02-01T00:00:00.000Z"
      }
    ]
  },
  "request_id": "7b82b7f7-4d13-497b-9f20-58d46fd7a510"
}

GET /usage/requests is the companion: your API request log, filterable by status, route, key, and request ID. It answers “what did we actually send” without needing your own logs, which is particularly useful for tracking down what consumed an allowance.

When the allowance runs out

Creating a new timer returns quota_exhausted with a details object naming the metric, the limit, the amount used, and the reset time. POST /timers/{timer_id}/duplicate fails the same way, since a duplicate is a new timer.

Everything else keeps working:

• Existing timers keep counting down
• Hosted pages, embeds, and email GIFs keep rendering
• Webhooks keep firing and retrying
• Reads, updates, and control actions all keep working

Raising the ceiling means a larger plan, or a Custom arrangement where timer volume, rate limit, key and destination counts, and retention windows are set individually. See API pricing.