API-Fehler verarbeiten

Die Calendar API gibt zwei Ebenen von Fehlerinformationen zurück:

  • HTTP-Fehlercodes und ‑Meldungen im Header
  • Ein JSON-Objekt im Antworttext mit zusätzlichen Details, die Ihnen helfen können, den Fehler zu beheben.

Im Weiteren werden auf dieser Seite die Struktur eines Fehlers beschrieben, einzelne Fehlercodes aufgezählt und es wird empfohlen, wie man am besten mit Fehlern umgehen kann.

Exponentiellen Backoff implementieren

In der Dokumentation zu Cloud APIs wird exponentieller Backoff und die Verwendung mit den Google APIs gut erläutert.

Fehler und vorgeschlagene Aktionen

In diesem Abschnitt finden Sie die vollständige JSON-Darstellung der einzelnen aufgeführten Fehler sowie Vorschläge für Maßnahmen, die Sie ergreifen können, um sie zu beheben.

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 den Vorgang nicht wiederholen. Lesen Sie stattdessen die Fehlermeldung und passen Sie Ihre Anfrage entsprechend an.

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 Aktionen:

  • Mit dem langlebigen Aktualisierungstoken ein neues Zugriffstoken abrufen.
  • Wenn das fehlschlägt, leiten Sie 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“ abgeschlossen haben.

403: User Rate Limit Exceeded (Ratenbegrenzung pro Nutzer überschritten)

Eines der Limits aus der Developer Console wurde erreicht.

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

Vorgeschlagene Aktionen:

403: Ratenlimit überschritten

Der Nutzer hat die maximale Anfragerate der Google Calendar 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 die Fehlercodes 403 oder 429 zurückgeben. Derzeit sind sie funktional ähnlich und sollten auf dieselbe Weise behandelt werden, nämlich mit exponentiellem Backoff. Außerdem muss Ihre App die Best Practices für die Verwaltung von Kontingenten einhalten.

403: Nutzungslimits für Kalender überschritten

Der Nutzer hat eines der Google Kalender-Limits erreicht, die zum Schutz von Google-Nutzern und der Infrastruktur vor missbräuchlichem Verhalten gelten.

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

Vorgeschlagene Aktionen:

403: Für Nicht-Organisatoren nicht zulässig

Mit der Anfrage zur Aktualisierung des Termins 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 Aktionen:

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

404: Nicht gefunden

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

  • wenn die angeforderte Ressource (mit der angegebenen ID) nie vorhanden war

  • wenn auf einen Kalender zugegriffen wird, 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 exponentiellen Backoff.

409: Die angeforderte Kennung ist bereits vorhanden

Eine Instanz mit der angegebenen ID ist im Speicher bereits 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 Batch-Element in einem events.batch-Vorgang kann aufgrund eines betrieblichen Konflikts mit anderen angeforderten Batch-Elementen nicht ausgeführt werden.

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

Vorgeschlagene Maßnahme:Schließen Sie alle erfolgreich abgeschlossenen und alle definitiv fehlgeschlagenen Batch-Elemente aus und versuchen Sie es mit den verbleibenden Elementen noch einmal in einem anderen events.batch oder entsprechenden Einzelereignisvorgängen.

410: Gone

Die Parameter syncToken oder updatedMin sind nicht mehr gültig. Dieser Fehler kann auch auftreten, wenn in 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 Speicher und synchronisieren Sie ihn 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 „If-Match“-Header 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 die Fehlercodes 403 oder 429 zurückgeben. Derzeit sind sie funktional ähnlich und sollten auf dieselbe Weise behandelt werden, nämlich mit exponentiellem Backoff. Außerdem muss Ihre App die Best Practices für die Verwaltung von Kontingenten einhalten.

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 exponentiellen Backoff.