Rate Limits

API requests are rate-limited per API key. Handle 429 responses with backoff and retries.

Limits

Rate limits are applied per API key:

/api/v1/* — 300 requests per 5 minutes (typical REST usage)
/api/ai/* — 20 requests per minute (AI query endpoints)

When exceeded, the API returns 429 Too Many Requests with a JSON body describing the error.

Handling 429 Responses

Implement exponential backoff: wait before retrying, and increase the wait on repeated 429s.

def with_retry
  tries = 0
  begin
    yield
  rescue RateLimitError => e
    tries += 1
    raise if tries > 5
    sleep(2 ** tries)
    retry
  end
end

Best practices

Batch or cache where possible. Use updated_since and pagination to avoid large one-off reads. For high-volume sync, consider webhooks instead of polling.