Rate limits & quotas

Limits come in two flavours: a per-key rate limit that smooths burst traffic, and a monthly quota that caps total volume.

Per-key rate limits

The rate limiter is a sliding window keyed by your clf_ API key. The defaults are:

Exceeding either window returns HTTP 429 with a Retry-After header (1 for per-second, 60 for per-minute).

Higher limits are available on the API and Custom plans — contact api@clarifo.com.

Monthly quota

Each key has a monthly_quota set when it is created (default 10,000 per month on Pro). Once you hit it you receive HTTP 429 with the response detail:

"Monthly quota exceeded (10000 requests). Upgrade your plan or wait until next month."

The header X-Clarifo-Quota-Used reports your current consumption so you can watch utilisation client-side. Counters reset at the start of each calendar month (UTC).

Counting model

Only successful calls and tool-level miss responses (HTTP 200 with an error field) count against the quota. Auth failures (401, 403) and rate-limit rejections (429) do not count, so a misconfigured client cannot drain your quota.

Data API consumption is tracked under feature_type = 'data_api' in your admin usage view, separately from the Weaviate proxy (weaviate_api) and the MCP server (mcp_tool).