Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Nutzungsbeschränkungen

Für die Google Calendar API gelten Kontingente, um eine faire Nutzung durch alle Nutzer zu gewährleisten. Bei der Verwendung der Calendar API sind drei wichtige Einschränkungen zu beachten:

API-Nutzungskontingente: Werden pro Projekt und pro Nutzer erzwungen. Weitere Informationen finden Sie unter Kontingenttypen für die Nutzung der Calendar API.
Allgemeine Nutzungslimits für Google Kalender: Die Google Calendar API ist ein gemeinsam genutzter Dienst, der Einschränkungen unterliegt, um die Gesamtleistung des Google Workspace-Systems zu schützen. Weitere Informationen finden Sie unter Nutzungslimits für Google Kalender vermeiden.
Betriebliche Limits: Diese Limits können jederzeit eingeschränkt werden. Das kann beispielsweise passieren, wenn Sie versuchen, in schneller Folge in einen einzelnen Kalender zu schreiben.

Calendar API-Kontingente

Es werden zwei Arten von Kontingenten erzwungen:

Pro Minute und Projekt: Dies ist die Anzahl der Anfragen, die Ihr Google Cloud-Projekt in einer Minute senden kann.
Pro Minute, Nutzer und Projekt: Dies ist die Anzahl der Anfragen, die ein bestimmter Nutzer in Ihrem Cloud-Projekt stellen kann. Dieses Limit soll Ihnen helfen, eine faire Verteilung der Nutzung auf Ihre Nutzer zu gewährleisten.

Kontingente werden pro Minute über ein Gleitfenster berechnet. Ein schneller Traffic-Anstieg, der Ihr Minutenkontingent innerhalb einer Minute überschreitet, führt im nächsten Zeitfenster zu einer Ratenbegrenzung, damit Ihre Nutzung im Durchschnitt innerhalb der Kontingente bleibt.

In der folgenden Tabelle werden diese Limits im Detail beschrieben:

Typ des Nutzungslimits	Limit
Pro Minute und Projekt	10.000 Anfragen
Pro Minute, Nutzer und Projekt	600 Anfragen

Täglicher Schwellenwert für die Abrechnung

Dieses Limit pro Tag und Projekt definiert die maximale Anzahl von Anfragen, die Ihr Google Cloud-Projekt innerhalb von 24 Stunden verwenden kann, bevor Gebühren anfallen.

Bei einer Nutzung unter diesem Schwellenwert fallen keine zusätzlichen Gebühren an und Ihr Google Cloud-Konto wird nicht belastet. Die vollständigen Abrechnungsdetails werden im Laufe des Jahres 2026 bekannt gegeben, mindestens 90 Tage vor Inkrafttreten der Änderungen.

Sie können keine Erhöhung dieses täglichen Grenzwerts beantragen.

In der folgenden Tabelle wird das Limit näher erläutert:

Art des Limits	Limit
Pro Tag und Projekt	1.000.000 Anfragen

Weitere Informationen finden Sie unter Standardisiertes Google Workspace-Modell für Agent-Tools und APIs.

Zeitbasierte Kontingentfehler beheben

Bei allen zeitbasierten Fehlern (maximal N Anfragen pro X Minuten) empfehlen wir, dass Ihr Code die Ausnahme abfängt und einen abgeschnittenen exponentiellen Backoff verwendet, damit Ihre Geräte keine übermäßige Last erzeugen.

Der exponentielle Backoff ist eine Standardstrategie zur Fehlerbehandlung für Netzwerkanwendungen. Ein exponentieller Backoff-Algorithmus wiederholt Anfragen mit exponentiell zunehmenden Wartezeiten zwischen den Anfragen bis zur maximalen Backoff-Zeit. Wenn Anfragen weiterhin fehlschlagen, ist es wichtig, dass die Verzögerungen zwischen den Anfragen im Laufe der Zeit zunehmen, bis die Anfrage erfolgreich ist.

Beispielalgorithmus

Ein exponentieller Backoff-Algorithmus wiederholt Anfragen exponentiell und verlängert dabei die Wartezeit zwischen zwei Wiederholungen bis zur maximalen Backoff-Zeit. Beispiel:

Stellen Sie eine Anfrage an die Google Calendar API.
Wenn die Anfrage fehlschlägt, wartet das System 1 + random_number_milliseconds und wiederholt dann die Anfrage.
Wenn die Anfrage fehlschlägt, wartet das System 2 + random_number_milliseconds Sekunden und wiederholt dann die Anfrage.
Wenn die Anfrage fehlschlägt, wartet das System 4 + random_number_milliseconds Sekunden und wiederholt dann die Anfrage.
Und so weiter bis zur maximum_backoff-Zeit.
Setzen Sie die Wartezeit fort und wiederholen Sie den Vorgang bis zu einer maximalen Anzahl an Wiederholungsversuchen. Erhöhen Sie jedoch nicht die Wartezeit zwischen den Wiederholungsversuchen.

Dabei gilt:

Die Wartezeit beträgt min(((2^n)+random_number_milliseconds), maximum_backoff), wobei n bei jeder Ausführung (Anfrage) um 1 erhöht wird.
random_number_milliseconds steht für eine zufällige Anzahl von Millisekunden,deren Wert kleiner oder gleich 1.000 ist. So wird vermieden, dass viele Clients durch eine bestimmte Situation synchronisiert werden und alle gleichzeitig Wiederholungsversuche starten und Anfragen in synchronisierten Wellen senden. Der Wert von random_number_milliseconds wird nach jeder Anfragewiederholung neu berechnet.
maximum_backoff ist normalerweise 32 oder 64 Sekunden lang. Der geeignete Wert hängt vom jeweiligen Anwendungsfall ab.

Der Client kann den Vorgang wiederholen, nachdem er die maximum_backoff-Zeit erreicht hat. Die Backoff-Zeit muss dabei nicht mehr verlängert werden. Wenn ein Client beispielsweise eine maximum_backoff-Zeit von 64 Sekunden verwendet, kann er den Vorgang nach Erreichen dieses Werts alle 64 Sekunden noch einmal versuchen. Sie sollten jedoch dafür sorgen, dass er dies nicht unbegrenzt tut.

Die Wartezeit zwischen den Wiederholungen und der Anzahl der Wiederholungen hängt von Ihrem Anwendungsfall und den Netzwerkbedingungen ab.

Preise

Die Standardnutzung der Google Calendar API ist ohne zusätzliche Kosten möglich. Wenn Sie die Kontingentlimits für Anfragen überschreiten, fallen voraussichtlich im Laufe des Jahres 2026 Gebühren für Ihr Google Cloud-Rechnungskonto an. Weitere Informationen finden Sie unter Standardisiertes Google Workspace-Modell für Agent-Tools und APIs.

Kontingenterhöhung anfordern

Abhängig von der Ressourcennutzung Ihres Projekts möchten Sie möglicherweise eine Kontingentanpassung anfordern. API-Aufrufe durch ein Dienstkonto werden so behandelt, als würden sie von einem einzelnen Konto stammen. Wenn Sie ein angepasstes Kontingent beantragen, bedeutet dies nicht, dass Ihr Antrag auch genehmigt wird. Anfragen zur Kontingentanpassung, die den Kontingentwert erheblich erhöhen würden, können länger dauern, bis sie genehmigt werden.

Es gelten nicht für alle Projekte dieselben Kontingente. Wenn Sie Google Cloud mit der Zeit stärker nutzen, müssen Ihre Kontingentwerte möglicherweise erhöht werden. Falls Sie eine deutlich stärkere Auslastung erwarten, können Sie auf der Seite Kontingente und Systemlimits der Google Cloud Console eine Anpassung Ihres Kontingents anfordern.

Weitere Informationen finden Sie in folgenden Dokumenten:

Fehlerbehebung

Wenn eines der Kontingente überschritten wird, wird die Ratenbegrenzung angewendet und Sie erhalten als Antwort auf Ihre Abfragen den Statuscode 403 usageLimits oder 429 usageLimits.

In diesem Fall können Sie Folgendes versuchen:

Beachten Sie alle Best Practices: Verwenden Sie exponentiellen Backoff, randomisieren Sie Traffic-Muster und verwenden Sie Push-Benachrichtigungen.
Wenn Ihr Projekt wächst und Sie mehr Nutzer haben, können Sie eine Kontingenterhöhung anfordern.
Wenn Sie die Kontingentlimits pro Nutzer erreichen, können Sie Folgendes tun:
- Wenn Sie ein Dienstkonto verwenden, verteilen Sie die Last auf Nutzer oder auf mehrere Dienstkonten.
- Sie können zwar eine Erhöhung des Kontingents pro Nutzer anfordern, es wird jedoch im Allgemeinen nicht empfohlen, es über den Standardwert hinaus zu erhöhen, da Ihre Anwendung dann möglicherweise andere Arten von Limits erreicht, z. B. allgemeine Nutzungslimits für die Kalendernutzung oder operative Limits.
Testen Sie Ihre Kontingentlimits, indem Sie ein separates Testprojekt mit einer ähnlichen Konfiguration wie Ihr Produktionsprojekt registrieren. Weitere Informationen finden Sie unter Umgang mit Kontingentlimits testen.

Trafficmuster zufällig anordnen

Kalenderclients sind anfällig für Traffic-Spitzen, die durch mehrere Clients verursacht werden, die gleichzeitig Vorgänge ausführen. Eine gängige, aber schlechte Praxis für einen Kalender-Client ist beispielsweise, um Mitternacht eine vollständige Synchronisierung durchzuführen. Dies würde mit ziemlicher Sicherheit dazu führen, dass Ihr Kontingent pro Minute überschritten wird, was zu Ratenbegrenzungen und Backoffs führt.

Um dies zu vermeiden, sollten Sie Ihren Traffic nach Möglichkeit über den Tag verteilen. Wenn Ihr Client eine tägliche Synchronisierung durchführen muss, sollte er eine zufällige Zeit festlegen (für jeden Client unterschiedlich). Wenn Sie einen Vorgang regelmäßig ausführen müssen, variieren Sie das Intervall um +/- 25 %. Dadurch wird der Traffic gleichmäßiger verteilt und die Nutzerfreundlichkeit deutlich verbessert.

Push-Benachrichtigungen verwenden

Ein häufiger Anwendungsfall ist, eine Aktion auszuführen, wenn sich etwas im Kalender des Nutzers ändert. Ein Anti-Pattern wäre hier, jeden relevanten Kalender wiederholt abzufragen. Dadurch wird Ihr Kontingent sehr schnell aufgebraucht. Wenn Ihre Anwendung beispielsweise 5.000 Nutzer hat und den Kalender jedes Nutzers einmal pro Minute abfragt, ist ein Kontingent von mindestens 5.000 Anfragen pro Minute erforderlich, noch bevor irgendwelche Arbeit erledigt wird.

Serverseitige Anwendungen können sich für Push-Benachrichtigungen registrieren, damit wir Sie benachrichtigen können, wenn etwas Interessantes passiert. Diese erfordern mehr Aufwand bei der Einrichtung, ermöglichen aber eine wesentlich effizientere Nutzung Ihres Kontingents und bieten eine bessere Nutzererfahrung. Geben Sie die eventType an, für die Sie benachrichtigt werden möchten. Weitere Informationen finden Sie unter Push-Benachrichtigungen.

Richtige Zuordnung mit Dienstkonten

Wenn Ihre Anwendung Anfragen mit domainweiter Delegierung ausführt, wird standardmäßig das Dienstkonto mit den Kontingenten „pro Minute pro Nutzer pro Projekt“ belastet und nicht der Nutzer, dessen Identität Sie übernehmen. Das bedeutet, dass das Dienstkonto wahrscheinlich das Kontingent überschreitet und die Rate begrenzt wird, auch wenn es möglicherweise für die Kalender mehrerer Nutzer verwendet wird.

Sie können dies vermeiden, indem Sie den URL-Parameter quotaUser (oder den HTTP-Header x-goog-quota-user) verwenden, um einen beliebigen String (bis zu 40 Zeichen) anzugeben, der jeden einzelnen Nutzer eindeutig identifiziert. Die Calendar API verwendet diesen Wert nur für Kontingentberechnungen.

Wenn Sie quotaUser verwenden möchten, um nutzerspezifische Ratenbegrenzungen für verschiedene Nutzer zu erzwingen, müssen Ihre Anfragen die folgenden Anforderungen erfüllen:

API-Schlüssel mit IP-Einschränkung einfügen: Übergeben Sie einen API-Schlüssel im Suchparameter key und konfigurieren Sie diesen Schlüssel mit IP-Adresseinschränkungen, die die öffentlichen IP-Adressen Ihrer Backend-Server angeben. Wenn Sie den API-Schlüssel weglassen oder keine IP-Adresseinschränkungen konfigurieren, ignoriert die Calendar API quotaUser und rechnet das Kontingent dem authentifizierten Konto (z. B. dem Dienstkonto) an.
X-Goog-User-Project-Header weglassen: Senden Sie keinen X-Goog-User-Project-HTTP-Header bei Anfragen, die quotaUser verwenden. Wenn Sie ein Nutzerprojekt angeben, wird der API-Schlüssel für die Kontingentzuordnung überschrieben. Die Calendar API ignoriert dann quotaUser.

Weitere Informationen finden Sie unter Anfragen pro Nutzer begrenzen.

Umgang mit Kontingentlimits testen

Damit Ihre Anwendung in der Praxis das Erreichen von Kontingentlimits ordnungsgemäß verarbeiten kann (z. B. durch Wiederholungsversuche mit exponentiellem Backoff) und um potenzielle Störungen für Ihre Nutzer zu minimieren, empfehlen wir dringend, Ihr Szenario in einer realen Umgebung zu testen.

Wenn Sie Tests durchführen möchten, ohne die tatsächliche Nutzung Ihrer Anwendung zu beeinträchtigen, empfehlen wir, in der Google Cloud Console ein separates Testprojekt zu registrieren und dann den OAuth-Zustimmungsbildschirm ähnlich wie bei Ihrem Produktionsprojekt zu konfigurieren. Sie können dann künstlich niedrige Kontingentlimits für dieses Projekt festlegen und das Verhalten Ihrer Anwendung beobachten.

Kontingente für den MCP-Server für Google Kalender

Der MCP-Server für Google Kalender verwendet einen Messwert für die Zuordnung von Abfragekosten. In den folgenden Tabellen sind die Abfragekosten für die einzelnen MCP-Servermethoden von Google Kalender nach Abschnitt aufgeführt:

MCP-Kontingente für Google Kalender