Rate Limits

Rate Limits

The public API applies rate limits in two layers, both scoped to /api/v1:

1. Pre-auth, per-IP — a conservative, flat limit applied before your key is even verified. This exists purely to blunt brute-force/credential-stuffing traffic against the authentication path itself.
2. Post-auth, per-key — the limit that matters day to day. It’s scoped to your API key and tiered by your organization’s plan.

Route classes

Limits are set per route class, not per individual endpoint, to keep the limit predictable across our curated surface:

Class	Applies to
read	GET/HEAD requests
search	Any route whose fixed path pattern includes /search
write	Everything else (POST, PUT, PATCH, DELETE)

Classification is based on the registered route pattern, never on the raw request URL or query string, so it can’t be gamed by appending arbitrary query parameters.

Tiers (per-key, requests/minute)

Tier	read	search	write
sandbox	30	15	10
free	60	30	20
starter	120	60	40
growth	300	150	100
plus	600	300	200
pro	1200	600	400
scale	3000	1500	1000
enterprise	6000	3000	2000

Your tier is derived from your organization’s plan automatically — there’s nothing to configure. A sandbox-environment key always uses the sandbox tier, regardless of your live organization’s actual plan.

The pre-auth IP limit is a flat 120 read / 60 search / 30 write requests per minute, identical for every caller — it exists only to protect the auth path, not to enforce per-plan fairness.

Headers

Every response from /api/v1 includes:

RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 1784178600

• RateLimit-Limit — the max requests allowed in the current window.
• RateLimit-Remaining — requests left in the current window.
• RateLimit-Reset — Unix timestamp (seconds) when the window resets.

When a request is rejected for being over the limit, the response also includes:

Retry-After: 42

Responses

Status	Meaning
429 RATE_LIMIT_EXCEEDED	Over the limit for your tier/route class
503 RATE_LIMITER_UNAVAILABLE	The rate limiter itself is unavailable

Fail closed, not fail open

If the rate limiter’s backing store is unreachable, requests are rejected (503), never silently allowed through unlimited. If you see a spike in 503 RATE_LIMITER_UNAVAILABLE, back off and retry — it means our infrastructure is degraded, not that your key did anything wrong.

Handling limits in your integration

• Read RateLimit-Remaining and slow down proactively — don’t wait for a 429.
• On 429 or 503, respect Retry-After before retrying; use exponential backoff with jitter for repeated failures.
• If you’re consistently hitting your tier’s limit, upgrading your plan raises the ceiling — no separate “API add-on” is required.

Google Sheets API Quota

v1.16.0

Google Sheets sync operations use Google’s Sheets API, which has its own quota separate from the clienta.ai API rate limits:

• Project-wide limit: 250 requests/minute across all organizations
• Per-org fairness: Maximum 3 concurrent sync jobs per organization
• Backoff: 429 responses from Google trigger exponential backoff automatically
• No action needed: These limits are managed server-side. If your sync is slow during peak usage, it will complete — just more slowly.