API-Fehler verarbeiten

Die Google 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.

Auf dieser Seite finden Sie eine Referenz zu Kalenderfehlern mit einigen Hinweisen dazu, wie Sie sie in Ihrer App beheben können.

Exponentiellen Backoff implementieren

In der Google Cloud Storage-Dokumentation wird der exponentielle Backoff erläutert und wie er mit Google APIs verwendet wird.

Fehler und empfohlene Maßnahmen

In diesem Abschnitt finden Sie die vollständige JSON-Darstellung der einzelnen aufgeführten Fehler und empfohlene Maßnahmen, die Sie zur Behebung ergreifen können.

400: Ungültige Anfrage

Nutzerfehler. Dieser Fehler tritt auf, wenn Sie ein Pflichtfeld oder einen Pflichtparameter nicht angeben, einen ungültigen Wert angeben oder eine ungültige Kombination von Feldern angeben.

{
  "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 ändern Sie Ihre Anfrage entsprechend.

401: Ungültige Anmeldedaten

Ungültiger Autorisierungsheader. Das 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"
  }
}

Empfohlene Maßnahmen :

  • Rufen Sie mit dem langlebigen Aktualisierungstoken ein neues Zugriffstoken ab.
  • Wenn dies fehlschlägt, leiten Sie den Nutzer durch den OAuth-Ablauf, wie unter Anfragen mit OAuth 2.0 autorisieren beschrieben.
  • Wenn dieser Fehler bei einem Dienstkonto auftritt, prüfen Sie, ob Sie alle Schritte auf der Seite des Dienstkontosausgeführt haben.

403: Ratenbegrenzung für Nutzer überschritten

Eines der Limits aus der Google Cloud Console wurde erreicht.

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

Empfohlene Maßnahmen :

403: Ratenbegrenzung überschritten

Der Nutzer hat die maximale Anforderungsrate der 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. Sie sind funktional ähnlich und sollten auf dieselbe Weise mit exponentiellem Backoff behandelt werden. Achten Sie außerdem darauf, dass Ihre App die Best Practices unter Kontingente verwalteneinhält.

403: Nutzungslimits für Kalender überschritten

Der Nutzer hat eines der Kalenderlimits erreicht, die eingerichtet wurden, um Google-Nutzer und die Infrastruktur vor missbräuchlichem Verhalten zu schützen.

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

Empfohlene Maßnahmen :

403: Unzulässig für Nicht-Organisator

Mit der Anfrage zur Terminaktualisierung wird versucht, eine der freigegebenen Termineigenschaften in einer Kopie festzulegen, die nicht vom Organisator stammt. Nur der Organisator kann freigegebene Eigenschaften festlegen (z. B. guestsCanInviteOthers, guestsCanModify oder guestsCanSeeOtherGuests).

{
  "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."
  }
}

Empfohlene Maßnahmen :

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

404: Nicht gefunden

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

  • Wenn die angeforderte Ressource (mit der angegebenen ID) nie vorhanden war.
  • 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 den exponentiellen Backoff.

409: Die angeforderte ID ist bereits vorhanden

Eine Instanz mit der angegebenen ID ist bereits im Speicher 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 die events.update Methode.

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"
  }
}

Empfohlene Maßnahme:Entfernen Sie abgeschlossene und fehlgeschlagene Elemente und wiederholen Sie die verbleibenden Elemente in einem anderen events.batch-Vorgang oder entsprechenden Einzelereignisvorgängen.

410: 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 Speicher und führen Sie eine erneute Synchronisierung durch. Weitere Informationen finden Sie unter Ressourcen effizient synchronisieren. Für bereits gelöschte Ereignisse sind keine weiteren Maßnahmen erforderlich.

412: 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 die Fehlercodes 403 oder 429 zurückgeben. Sie sind funktional ähnlich und sollten auf dieselbe Weise mit exponentiellem Backoff behandelt werden. Achten Sie außerdem darauf, dass Ihre App die Best Practices unter Kontingente verwalteneinhä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 den exponentiellen Backoff.