Limits and usage windows
The Casafari API and MCP Platform limits how fast and how much an account can call, per plan. This page lists those limits. They are the limits that clause 7.4 of the Terms of Use refers to when it says they are published in the Documentation. They apply over REST and MCP alike, and they are separate from what each call costs in units.
Limits per plan
| Limit | Free | Agent | Custom |
|---|---|---|---|
| Units | 1,000 for 30 days | 1,000 per rolling 3 hours and 4,000 per rolling 7 days | As agreed |
| Requests a minute | 10 | 20 | As agreed |
| Requests in flight at once | 2 | 3 | As agreed |
| Distinct places a day | 10 | 50 | As agreed |
| Requests per rolling 3 hours | 50 | No limit | As agreed |
| Requests a day | 100 | No limit | As agreed |
| Requests per rolling 7 days | 300 | No limit | As agreed |
| Units a day (hard daily cap) | 1,000 | 50,000 | As agreed |
| Page size | 25 results | Each operation's own maximum | As agreed |
| Page depth | 100 results (4 pages) of one search | Each operation's own maximum | As agreed |
| Spending cap on credits | Not applicable | 25,000 units per subscription period | As agreed |
| Members, API keys, OAuth clients | 1, 2, 2 | 3, 5, 5 | As agreed |
How to read it:
- A day runs from 00:00 UTC, and a minute is the current UTC minute. The rolling windows move continuously: usage leaves a window 3 hours or 7 days after it was made.
- Requests count whether or not they cost units: free calls such as place lookups, refunded calls and calls refused for payment all count. Place lookups and the account status check cost 0 units.
- A distinct place is a location a request names. Naming a place already used that day does not count again.
- The 1,000 units of Free are for the first 30 days. After that, place lookups and the account status check stay free and other calls return a payment link.
- Agent counts units, not requests, in its windows. Usage beyond a window is paid only from prepaid credits, and nothing is billed afterwards.
- A request over an operation's page size or depth maximum is refused with
400 page_depth_exceeded, and the response names the parameter and the maximum. - Custom limits are set in the contract.
Accounts on credits without a subscription
An account that has bought prepaid credits and has no subscription can only spend what it bought, so it has no 3-hour or 7-day window and no spending cap. Its guards are 20 requests a minute, 3 requests in flight, 50 distinct places a day and at most 25,000 units a day. Until the account has passed business verification, or until 7 days after its first credit purchase, it keeps the Free plan's guards on requests a minute (10), requests in flight (2) and distinct places a day (10).
Account creation
- At most 3 accounts are opened per network a day, across the console, the sign-up API and OAuth sign-in. Over it the answer is
429 signup_limited. - At most 3 sign-ups through the sign-up API are started per email address a day (UTC).
- The email code that confirms an address is valid for 10 minutes and takes 5 attempts. At most 3 codes are sent per email address in 15 minutes and 20 per network in an hour.
What happens at a limit
| Status | Problem type | When | What to do |
|---|---|---|---|
429 | request_limit_reached | A request guard is used up: requests in flight, a minute, 3 hours, a day, 7 days or distinct places. The window member names which one. | Wait for Retry-After seconds, then retry. |
429 | usage_limit_reached | An Agent usage window (session, 3 hours, or weekly, 7 days) is used up and no credits remain. Carries limit, reset_at, Retry-After and an upgrade_url to buy credits. | Wait until reset_at, or open upgrade_url to buy credits. |
429 | daily_limit_reached | The account's daily unit cap is reached. It resets at 00:00 UTC. | Retry after the reset. |
402 | payment_required | The units are used up. Carries upgrade_url and a Link header with rel="payment". | A person opens upgrade_url to pay. Poll GET /v1/account/payment-links/{id} about every 5 seconds until it is completed, then retry. |
402 | payment_required with reason spending_cap_reached | On Agent, the credits spent this period reached the spending cap. | Wait for the next period, or raise the cap in the account's billing settings. |
400 | page_depth_exceeded | Page size or page depth is over the maximum. | Ask for fewer results, or stop paging. |
Errors are application/problem+json, and each type has a page at https://platform.casafari.com/errors/<code>. Over MCP the same refusals arrive as a payment error or a tool error with the same members. An agent cannot pay by itself: a person opens the payment link.
The spending cap limits the credits an Agent subscription spends in one subscription period, automatic top-ups included. The default is 25,000 units (EUR 1,000). When it is reached, calls that would use credits are refused and no automatic top-up is made until the period ends or the cap is raised. Calls within the usage windows continue.
These limits protect the stability of the platform. Custom contracts set their own. The limits of the existing Casafari MCP server and REST API follow each customer's own contract and are not listed here. Claro AI, a platform product, is metered in platform units, with Claro's own limits per account behind them: see Limits and errors.
See also: Terms of Use (clauses 7 and 8), REST API and the FAQ.
Questions about this
- What plans does the Casafari self-serve platform offer: Free, Agent and Custom?
- What are the 3-hour and weekly usage windows on the Agent plan, and what does the console show?
- What are Casafari's rate limits, quotas and usage limits?
- Which Casafari errors should I retry, and which not?
- Which errors does the Casafari REST API return, and which should I retry?