Limits und Nutzungszeiträume
Die Casafari API- und MCP-Plattform begrenzen je nach Plan, wie schnell und wie viele Aufrufe ein Konto tätigen kann. Diese Seite listet diese Limits auf. Es handelt sich um die Limits, auf die sich Klausel 7.4 der Nutzungsbedingungen bezieht, wenn dort erwähnt wird, dass diese in der Dokumentation veröffentlicht sind. Sie gelten gleichermaßen für REST und MCP und sind unabhängig von den Token-Kosten pro Aufruf.
Limits je Plan
| Limit | Free | Agent | Agency | Business | Custom |
|---|---|---|---|---|---|
| Tokens | 1.000 für 30 Tage, maximal 500 pro gleitendem 3-Stunden-Zeitraum | 1.500 pro Monat, maximal 600 pro gleitendem 3-Stunden-Zeitraum | 10.000 monatlich, maximal 3.000 pro gleitendem 3-Stunden-Fenster | 50.000 monatlich, maximal 15.000 pro gleitendem 3-Stunden-Fenster | Wie vereinbart |
| Anfragen pro Minute | 6 | 20 | 20 | 20 | Wie vereinbart |
| Gleichzeitige Anfragen | 2 | 3 | 3 | 3 | Wie vereinbart |
| Verschiedene Orte pro Tag | 10 | 50 | 50 | 50 | Wie vereinbart |
| Anfragen pro gleitendem 3-Stunden-Fenster | 50 | Unbegrenzt | Unbegrenzt | Unbegrenzt | Wie vereinbart |
| Anfragen pro Tag | 100 | Unbegrenzt | Unbegrenzt | Unbegrenzt | Wie vereinbart |
| Anfragen pro gleitendem 7-Tage-Fenster | 300 | Unbegrenzt | Unbegrenzt | Unbegrenzt | Wie vereinbart |
| Tokens pro Tag (festes Tageslimit) | 1,000 | 50,000 | 50,000 | 50,000 | Wie vereinbart |
| Seitengröße | 25 Ergebnisse | Individuelles Maximum je Operation | Individuelles Maximum je Operation | Individuelles Maximum je Operation | Wie vereinbart |
| Seitentiefe | 100 Ergebnisse (4 Seiten) pro Suche | Individuelles Maximum je Operation | Individuelles Maximum je Operation | Individuelles Maximum je Operation | Wie vereinbart |
| Ausgabenlimit für Credits | Nicht anwendbar | 25.000 Tokens pro Abonnementzeitraum | 25.000 Tokens pro Abonnementzeitraum | 25.000 Tokens pro Abonnementzeitraum | Wie vereinbart |
| Mitglieder, API-Keys, OAuth-Clients | 1, 2, 2 | 1, 3, 3 | 10, 20, 20 | 50, 50, 50 | Wie vereinbart |
Preise finden Sie unter Preise.
So lesen Sie die Angaben:
- Ein Tag beginnt um 00:00 Uhr UTC, und eine Minute entspricht der aktuellen UTC-Minute. Die gleitenden Fenster bewegen sich kontinuierlich: Die Nutzung fällt 3 Stunden bzw. 7 Tage nach der jeweiligen Anfrage aus dem Fenster.
- Anfragen werden gezählt, unabhängig davon, ob sie Tokens verbrauchen: Kostenfreie Abrufe wie Ortssuchen (
locations_search), zurückerstattete Abrufe sowie aus Zahlungsgründen abgelehnte Anfragen zählen mit. Zwei Abrufe zählen niemals mit, sodass ein Nutzer jederzeit den Kontostand einsehen und eine Zahlung abschließen kann: die Kontostatusabfrage (account_status,GET /v1/account) und der Status des Zahlungslinks (GET /v1/account/payment-links/{id}). Ortssuchen und die Kontostatusabfrage kosten 0 Tokens. - Ein bestimmter Ort ist eine in der Anfrage genannte Lokalität: ein
location_idsowie ein Kreis, ein Polygon oder eine Straßenadresse (Comparables akzeptiert eine Adresse oder einen Kreis). Das Nennen eines bereits am Tag genutzten Ortes zählt nicht erneut. Kostenfreie Abfragen zählen ebenfalls zum Limit von 10 Orten; ein Nutzer, der viele Orte abfragt, erreicht also das Tageslimit für Orte, bevor er eine kostenpflichtige Anfrage stellt. - Im Plan Free gelten die Limits gemeinsam: Sobald das erste Limit erreicht ist, wird die nächste Anfrage gestoppt.
- Die 1.000 Tokens des Plans Free gelten für die ersten 30 Tage. Danach bleiben Ortssuchen und die Kontostatusabfrage kostenfrei, während andere Aufrufe einen Zahlungslink zurückgeben. Maximal 500 davon können innerhalb von 3 Stunden genutzt werden.
- Agent, Agency und Business basieren auf der Anzahl der Tokens, nicht der Anfragen: Es gilt das monatliche Token-Kontingent sowie ein maximaler Wert innerhalb von 3 Stunden. Die Nutzung darüber hinaus wird ausschließlich über Prepaid-Guthaben abgerechnet; es erfolgen keine nachträglichen Rechnungen. Nicht verbrauchte Tokens verfallen am Ende des Monats.
- Wird bei einer Operation die maximale Seitengröße oder -tiefe überschritten, wird die Anfrage mit
400 page_depth_exceededabgelehnt. Die Antwort gibt den betroffenen Parameter sowie den Maximalwert an. - Individuelle Limits werden vertraglich vereinbart.
Claro AI im Free-Plan
Für Claro AI gilt im Free-Plan eine eigene Obergrenze: Insgesamt 4 Suchanfragen, unabhängig von der Art der Suche und der Reihenfolge, gelten für die gesamte Organisation. Die Nutzung über REST und MCP wird hierbei gemeinsam gezählt.
- Als Suche gelten
claro_search_premises(POST /v1/claro/search),claro_refine_search(POST /v1/claro/search/refine) oderclaro_search_plots(POST /v1/claro/plots/search). Jede Seite zählt als eine Suchanfrage: Das Abrufen einer Folgeseite mittels Cursor oder Offset wird erneut als Suche gewertet. - Es können nur Ergebnisse dieser Suchanfragen geöffnet werden:
claro_get_premises,claro_get_plotundclaro_compare_premisesfunktionieren nur mit den IDs, die durch diese Suchen geliefert wurden. Details zu anderen IDs werden verweigert. - Die 5. Suchanfrage oder ein Detailabruf einer anderen ID wird mit
402 payment_requiredund dem Grundtrial_limitabgelehnt. Die Antwort enthält einenupgrade_url, über den der Kontoinhaber oder eine für die Abrechnung zuständige Person Credits erwerben kann; der Kauf von Tokens erfordert kein Abonnement und hebt das Limit auf. Der Free-Plan umfasst 4 Claro AI-Suchanfragen inklusive ihrer Ergebnisse; bei Erreichen des Limits sollte die Anwendung pausieren und einen entsprechenden Hinweis ausgeben, statt die Anfrage zu wiederholen. Suchanfragen, auf die Claro keine Antwort lieferte, werden nicht gezählt. - Claro-Operationen, die keine Tokens verbrauchen, unterliegen nicht dieser Obergrenze. Suchanfragen kosten auch hier Tokens gemäß Ihrem Plan, und die oben genannten Anfrage-Limits gelten ebenso für Claro-Aufrufe. Bezahlte Pläne haben kein Such-Limit.
Konten mit Credits ohne Abonnement
Ein Konto, das Prepaid-Guthaben erworben hat und über kein Abonnement verfügt, kann nur das erworbene Guthaben ausgeben und hat daher kein 3-Stunden- oder 7-Tage-Fenster und kein Ausgabenlimit. Die Schutzmechanismen liegen bei 20 Anfragen pro Minute, 3 gleichzeitigen Anfragen, 50 unterschiedlichen Standorten pro Tag und maximal 25.000 Tokens pro Tag. Bis das Konto die geschäftliche Verifizierung durchlaufen hat oder bis 7 Tage nach dem ersten Guthabenkauf vergangen sind, gelten weiterhin die Schutzmechanismen des Free-Plans für Anfragen pro Minute (6), gleichzeitige Anfragen (2) und unterschiedliche Standorte pro Tag (10). Der Guthabenkauf erfordert eine verifizierte Karte; in den ersten 7 Tagen nach Kartenverifizierung ist ein Kauf auf maximal 4.000 € begrenzt.
Kontoerstellung
- Pro Netzwerk können täglich maximal 3 Konten eröffnet werden, verteilt auf die Konsole, die Registrierungs-API und den OAuth-Login. Bei Überschreitung erfolgt die Antwort
429 signup_limited. - Pro E-Mail-Adresse können täglich (UTC) maximal 3 Registrierungen über die Registrierungs-API gestartet werden.
- Der Bestätigungscode per E-Mail ist 10 Minuten lang gültig und erlaubt 5 Versuche. Pro E-Mail-Adresse können innerhalb von 15 Minuten maximal 3 Codes versendet werden, und maximal 20 pro Netzwerk innerhalb einer Stunde.
Status der Nutzung prüfen
Überprüfen Sie Ihre Nutzung mit dem account_status-Tool, das in den Location Lookup-, Area Insights- und Comparables-Servern verfügbar ist. Verwenden Sie hierfür GET https://platform.casafari.com/v1/account (mit Ihrem API-Key im X-API-Key-Header oder als Authorization: Bearer <api_key>) oder besuchen Sie die Konsole, die Ihnen den rollierenden 3-Stunden-Zeitraum, den heutigen Verbrauch seit 00:00 Uhr UTC sowie den rollierenden 7-Tage-Zeitraum anzeigt. Aufrufe des Kontostatus verbrauchen 0 Tokens.
Verhalten bei Erreichen eines Limits
| Status | Problemtyp | Zeitpunkt | Vorgehensweise |
|---|---|---|---|
429 | request_limit_reached | Ein Sicherheitslimit für Anfragen wurde erreicht: parallele Anfragen, Anfragen pro Minute, 3 Stunden, Tag, 7 Tage oder unterschiedliche Objekte. Das Feld window gibt an, welches Limit betroffen ist (siehe unten). | Warten Sie Retry-After Sekunden ab und versuchen Sie es dann erneut. |
429 | usage_limit_reached | Das 3-Stunden-Token-Fenster (session) eines Plans ist aufgebraucht und es sind keine Credits mehr vorhanden. Die Antwort enthält limit, reset_at, Retry-After sowie einen upgrade_url zum Erwerb von Credits. | Warten Sie bis reset_at oder nutzen Sie den upgrade_url, um Credits zu erwerben. |
429 | daily_limit_reached | Das tägliche Token-Limit des Kontos wurde erreicht. Es wird jeweils um 00:00 Uhr UTC zurückgesetzt. | Versuchen Sie es nach dem Zurücksetzen erneut. |
402 | payment_required | Die Tokens sind aufgebraucht. Enthält eine upgrade_url sowie einen Link-Header mit rel="payment". | Laden Sie unter upgrade_url Tokens nach (dies kann der Kontoinhaber oder ein für die Abrechnung autorisiertes Mitglied tun). Fragen Sie etwa alle 5 Sekunden über GET /v1/account/payment-links/{id} den Status ab, bis der Vorgang abgeschlossen ist, und versuchen Sie es dann erneut. |
402 | payment_required mit dem Grund spending_cap_reached | Für Agent, Agency und Business: Das verbrauchte Guthaben hat in diesem Zeitraum das Ausgabenlimit erreicht. | Warten Sie den nächsten Zeitraum ab oder erhöhen Sie das Limit in den Abrechnungseinstellungen des Kontos. |
400 | page_depth_exceeded | Die Seitengröße oder Seitentiefe überschreitet den zulässigen Höchstwert. | Fordern Sie weniger Ergebnisse an oder beenden Sie die Paginierung. |
Das window-Mitglied von request_limit_reached
window benennt das Anfragelimit, das überschritten wurde. Dies ist kein Token-Nutzungsfenster: Es gibt an, welche Zeile der obigen Tabelle die Anfrage verweigert hat, da ein Anfragelimit die Anzahl der Anfragen zählt, nicht die Tokens.
window | Das überschrittene Limit | Free | Agent, Agency und Business |
|---|---|---|---|
concurrency | Gleichzeitig laufende Anfragen (die noch aktiv und jünger als 120 Sekunden sind) | 2 | 3 |
minute | Anfragen innerhalb der aktuellen UTC-Minute | 6 | 20 |
session | Anfragen innerhalb eines rollierenden 3-Stunden-Zeitraums | 50 | Unbegrenzt |
day | Anfragen innerhalb eines UTC-Tages | 100 | Unbegrenzt |
week | Anfragen innerhalb eines rollierenden 7-Tage-Zeitraums | 300 | Unbegrenzt |
month | Anfragen innerhalb eines rollierenden 30-Tage-Zeitraums | Unbegrenzt | Unbegrenzt |
locations | Unterschiedliche Orte, die am UTC-Tag angefragt wurden | 10 | 50 |
Verwechseln Sie dies nicht mit dem Token-Nutzungsfenster der Pläne. Dies wird mit usage_limit_reached verweigert, welches Tokens zählt und das 3-Stunden-Fenster als session bezeichnet. Ein request_limit_reached mit window session bezieht sich auf die 3-Stunden-Anfrageanzahl, und week auf die 7-Tage-Anfrageanzahl. month wird nur für Konten mit eigenen Limits gesetzt, etwa bei Custom-Verträgen. Warten Sie die in Retry-After angegebene Sekundenanzahl ab, bis dieses Limit wieder freigegeben wird.
Fehler werden im Format application/problem+json zurückgegeben, wobei jeder Typ eine eigene Seite unter https://platform.casafari.com/errors/<code> hat. Über MCP kommen dieselben Verweigerungen als Zahlungs- oder Tool-Fehler mit identischen Mitgliedern an. Ein KI-Assistent kann die Zahlung nicht selbst vornehmen: Der Kontoinhaber oder ein berechtigtes Mitglied muss den Zahlungslink öffnen, um Tokens nachzuladen.
Das Ausgabenlimit begrenzt das Guthaben, das ein Agent-, Agency- oder Business-Abonnement pro Abrechnungszeitraum verbrauchen kann, einschließlich automatischer Aufladungen. Der Standardwert beträgt 25.000 Tokens (1.000 €). Bei Erreichen werden Anfragen, die Guthaben verbrauchen, abgelehnt und keine automatische Aufladung durchgeführt, bis der Zeitraum endet oder das Limit erhöht wird. Anfragen innerhalb der Nutzungsgrenzen bleiben weiterhin möglich.
Für die Plattform besteht kein SLA: Casafari ist um ständige Verfügbarkeit bemüht, garantiert jedoch keinen ununterbrochenen oder fehlerfreien Betrieb und veröffentlicht keine Uptime-Werte (siehe die Nutzungsbedingungen). Diese Limits dienen der Stabilität der Plattform. Bei Custom-Verträgen gelten individuelle Limits. Die Limits des bestehenden Casafari MCP-Servers und der REST API richten sich nach dem Vertrag des jeweiligen Kunden und sind hier nicht aufgeführt. Claro AI, ein Produkt der Plattform, wird in Plattform-Tokens abgerechnet, wobei für Claro eigene Limits pro Konto gelten: siehe Limits und Fehler.
Siehe auch: Nutzungsbedingungen (Abschnitte 7 und 8), REST API und die FAQ.