API-Fehler verarbeiten

Die Calendar API gibt zwei Fehlerebenen zurück:

  • HTTP-Fehlercodes und -meldungen im Header
  • Ein JSON-Objekt im Antworttext mit zusätzlichen Details, anhand derer Sie entscheiden können, wie Sie mit dem Fehler umgehen möchten.

Im Weiteren finden Sie auf dieser Seite eine Referenz zu Kalenderfehlern mit einigen Hinweisen dazu, wie Sie damit in Ihrer App umgehen können.

Exponentiellen Backoff implementieren

In der Dokumentation zu Cloud APIs wird die exponentielle Backoff-Methode und ihre Verwendung mit den Google APIs ausführlich erläutert.

Fehler und vorgeschlagene Maßnahmen

In diesem Abschnitt finden Sie die vollständige JSON-Darstellung der einzelnen aufgeführten Fehler und Vorschläge zur Fehlerbehebung.

400: Ungültige Anfrage

Nutzerfehler. Das kann bedeuten, dass ein erforderliches Feld oder ein erforderlicher Parameter nicht angegeben wurde, der angegebene Wert ungültig ist oder die Kombination der angegebenen Felder ungültig ist.

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "timeRangeEmpty",
    "message": "The specified time range is empty.",
    "locationType": "parameter",
    "location": "timeMax",
   }
  ],
  "code": 400,
  "message": "The specified time range is empty."
 }
}

Empfohlene Maßnahme:Da es sich um einen dauerhaften Fehler handelt, sollten Sie nicht noch einmal versuchen, den Vorgang auszuführen. Lesen Sie stattdessen die Fehlermeldung und ändern Sie Ihre Anfrage entsprechend.

401: Ungültige Anmeldedaten

Ungültiger Autorisierungsheader. Das von Ihnen verwendete Zugriffstoken ist entweder abgelaufen oder ungültig.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "authError",
    "message": "Invalid Credentials",
    "locationType": "header",
    "location": "Authorization",
   }
  ],
  "code": 401,
  "message": "Invalid Credentials"
 }
}

Vorgeschlagene Maßnahmen:

  • Rufe mit dem langlebigen Aktualisierungstoken ein neues Zugriffstoken ab.
  • Wenn das nicht funktioniert, leite den Nutzer durch den OAuth-Vorgang, wie unter Anfragen mit OAuth 2.0 autorisieren beschrieben.
  • Wenn Sie diese Meldung für ein Dienstkonto sehen, prüfen Sie, ob Sie alle Schritte auf der Seite „Dienstkonto“ ausgeführt haben.

403: Nutzerratenlimit überschritten

Eines der Limits in der Developer Console wurde erreicht.

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
   }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
 }
}

Vorgeschlagene Maßnahmen:

403: Ratenlimit überschritten

Der Nutzer hat die maximale Anfragerate der Google Kalender API pro Kalender oder pro authentifiziertem Nutzer erreicht.

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "rateLimitExceeded",
    "message": "Rate Limit Exceeded"
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

Empfohlene Maßnahme:rateLimitExceeded-Fehler können entweder 403- oder 429-Fehlercodes zurückgeben. Derzeit sind sie funktional ähnlich und sollten auf die gleiche Weise behandelt werden, indem der exponentielle Backoff verwendet wird. Außerdem müssen Sie dafür sorgen, dass Ihre App die Best Practices unter Kontingente verwalten einhält.

403: Nutzungslimits für Google Kalender überschritten

Der Nutzer hat eine der Google Kalender-Beschränkungen erreicht, die zum Schutz der Google-Nutzer und der Google-Infrastruktur vor missbräuchlichem Verhalten eingeführt wurden.

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Calendar usage limits exceeded.",
    "reason": "quotaExceeded"
   }
  ],
  "code": 403,
  "message": "Calendar usage limits exceeded."
 }
}

Vorgeschlagene Maßnahmen:

403: Unzulässig für Nutzer, die nicht der Organisator sind

Bei der Terminaktualisierungsanfrage wird versucht, eine der freigegebenen Termineigenschaften in einer Kopie festzulegen, die nicht dem Organisator gehört. Freigegebene Properties (z. B. guestsCanInviteOthers, guestsCanModify oder guestsCanSeeOtherGuests) können nur vom Organisator festgelegt werden.

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "forbiddenForNonOrganizer",
    "message": "Shared properties can only be changed by the organizer of the event."
   }
  ],
  "code": 403,
  "message": "Shared properties can only be changed by the organizer of the event."
 }
}

Vorgeschlagene Maßnahmen:

  • Wenn Sie Events: insert, Events: import oder Events: update verwenden und Ihre Anfrage keine freigegebenen Properties enthält, entspricht das dem Versuch, sie auf ihre Standardwerte festzulegen. Verwenden Sie stattdessen Ereignisse: patch.
  • Wenn Ihre Anfrage freigegebene Properties enthält, ändern Sie diese nur, wenn Sie die Kopie des Organisators aktualisieren.

404: Nicht gefunden

Die angegebene Ressource wurde nicht gefunden. Das kann in mehreren Fällen passieren. Hier einige Beispiele:

  • wenn die angeforderte Ressource (mit der angegebenen ID) noch nie existiert hat

  • beim Zugriff auf einen Kalender, auf den der Nutzer keinen Zugriff hat

    { "error": { "errors": [ { "domain": "global", "reason": "notFound", "message": "Not Found" } ], "code": 404, "message": "Not Found" } }

Empfohlene Maßnahme:Verwenden Sie exponentielles Backoff.

409: Die angeforderte Kennung ist bereits vorhanden

Im Speicher ist bereits eine Instanz mit der angegebenen ID vorhanden.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "duplicate",
    "message": "The requested identifier already exists."
   }
  ],
  "code": 409,
  "message": "The requested identifier already exists."
 }
}

Empfohlene Maßnahme:Generieren Sie eine neue ID, wenn Sie eine neue Instanz erstellen möchten. Andernfalls verwenden Sie den Methodenaufruf update.

409: Konflikt

Ein Element in einem Batch innerhalb eines events.batch-Vorgangs kann aufgrund eines operativen Konflikts mit anderen angeforderten Batchelementen nicht ausgeführt werden.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conflict",
    "message": "Conflict"
   }
  ],
  "code": 409,
  "message": "Conflict"
 }
}

Empfohlene Maßnahme:Schließen Sie alle erfolgreich abgeschlossenen und alle eindeutig fehlgeschlagenen Batch-Elemente aus und wiederholen Sie den Vorgang für die verbleibenden Elemente in einem anderen events.batch-Vorgang oder in entsprechenden Vorgängen für einzelne Ereignisse.

410: Gone (Nicht mehr vorhanden)

Die Parameter syncToken oder updatedMin sind nicht mehr gültig. Dieser Fehler kann auch auftreten, wenn mit einer Anfrage versucht wird, ein Ereignis zu löschen, das bereits gelöscht wurde.

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "fullSyncRequired",
    "message": "Sync token is no longer valid, a full sync is required.",
    "locationType": "parameter",
    "location": "syncToken",
    }
  ],
  "code": 410,
  "message": "Sync token is no longer valid, a full sync is required."
 }
}

oder

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "updatedMinTooLongAgo",
    "message": "The requested minimum modification time lies too far in the past.",
    "locationType": "parameter",
    "location": "updatedMin",
   }
  ],
  "code": 410,
  "message": "The requested minimum modification time lies too far in the past."
 }
}

oder

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "deleted",
    "message": "Resource has been deleted"
   }
  ],
  "code": 410,
  "message": "Resource has been deleted"
 }
}

Empfohlene Maßnahme:Löschen Sie für die Parameter syncToken oder updatedMin den Cache und synchronisieren Sie die Daten noch einmal. Weitere Informationen finden Sie unter Ressourcen effizient synchronisieren. Bei bereits gelöschten Ereignissen sind keine weiteren Maßnahmen erforderlich.

412: Precondition Failed (Vorbedingung fehlgeschlagen)

Das im Header „If-Match“ angegebene ETag entspricht nicht mehr dem aktuellen ETag der Ressource.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conditionNotMet",
    "message": "Precondition Failed",
    "locationType": "header",
    "location": "If-Match",
    }
  ],
  "code": 412,
  "message": "Precondition Failed"
 }
}

Empfohlene Maßnahme: Rufen Sie die Entität noch einmal ab und wenden Sie die Änderungen noch einmal an. Weitere Informationen finden Sie unter Bestimmte Versionen von Ressourcen abrufen.

429: Zu viele Anfragen

Ein rateLimitExceeded-Fehler tritt auf, wenn der Nutzer innerhalb eines bestimmten Zeitraums zu viele Anfragen gesendet hat.

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "rateLimitExceeded",
        "message": "Rate Limit Exceeded"
      }
    ],
    "code": 429,
    "message": "Rate Limit Exceeded"
  }
}

Empfohlene Maßnahme:rateLimitExceeded-Fehler können entweder 403- oder 429-Fehlercodes zurückgeben. Derzeit sind sie funktional ähnlich und sollten auf die gleiche Weise behandelt werden, also mit dem exponentiellen Backoff. Außerdem müssen Sie dafür sorgen, dass Ihre App die Best Practices unter Kontingente verwalten einhält.

500: Backend-Fehler

Beim Verarbeiten der Anfrage ist ein unerwarteter Fehler aufgetreten.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
   }
  ],
  "code": 500,
  "message": "Backend Error"
 }
}

Empfohlene Maßnahme:Verwenden Sie exponentielles Backoff.