Fehler beheben.

Die Gmail API gibt zwei Ebenen mit Fehlerinformationen zurück:

  • HTTP-Fehlercodes und -Meldungen im Header.
  • Ein JSON-Objekt im Antworttext mit zusätzlichen Details, anhand derer Sie ermitteln können, wie der Fehler behoben werden soll.

Gmail-Anwendungen sollten alle Fehler erfassen und verarbeiten, die bei der Verwendung der REST API auftreten können. In diesem Leitfaden finden Sie eine Anleitung zum Beheben bestimmter API-Fehler.

400-Fehler beheben: Fehlerhafte Anfrage

Dieser Fehler kann folgende Ursachen haben:

  • Ein Pflichtfeld oder Parameter wurde nicht angegeben.
  • Der angegebene Wert oder eine Kombination aus vorgegebenen Feldern ist ungültig.
  • Ungültiger Anhang.

Im Folgenden finden Sie ein Beispiel für eine JSON-Darstellung dieses Fehlers:

{
  "error": {
    "code": 400,
    "errors": [
      {
        "domain": "global",
        "location": "orderBy",
        "locationType": "parameter",
        "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
        "reason": "badRequest"
      }
    ],
    "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
  }
}

Um diesen Fehler zu beheben, überprüfen Sie das Feld message und passen Sie Ihren Code entsprechend an.

Fehler 401 beheben: Ungültige Anmeldedaten

Ein 401-Fehler gibt an, dass das von Ihnen verwendete Zugriffstoken entweder abgelaufen oder ungültig ist. Dieser Fehler kann auch durch fehlende Autorisierung für die angeforderten Bereiche verursacht werden. Im Folgenden sehen Sie die JSON-Darstellung dieses Fehlers:

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

Aktualisieren Sie das Zugriffstoken mit dem langlebigen Aktualisierungstoken, um diesen Fehler zu beheben. Wenn Sie eine Clientbibliothek verwenden, wird die Tokenaktualisierung automatisch durchgeführt. Wenn dies fehlschlägt, führe den Nutzer wie unter Anwendung mit Gmail autorisieren beschrieben durch den OAuth-Ablauf.

Weitere Informationen zu Gmail-Beschränkungen finden Sie unter Nutzungslimits.

Fehler 403 beheben: Nutzungslimit überschritten

Der Fehler 403 tritt auf, wenn ein Nutzungslimit überschritten wurde oder der Nutzer nicht die erforderlichen Berechtigungen hat. Um den spezifischen Fehlertyp zu ermitteln, werten Sie das Feld reason der zurückgegebenen JSON aus. Dieser Fehler tritt in den folgenden Situationen auf:

  • Das Tageslimit wurde überschritten.
  • Die Ratenbegrenzung für Nutzer wurde überschritten.
  • Das Ratenlimit für Projekte wurde überschritten.
  • Ihre App kann innerhalb der Domain des authentifizierten Nutzers nicht verwendet werden.

Weitere Informationen zu Gmail-Beschränkungen finden Sie unter Nutzungslimits.

Fehler 403 beheben: Tageslimit überschritten

Der Fehler dailyLimitExceeded gibt an, dass das API-Limit für Ihr Projekt erreicht wurde. Im Folgenden sehen Sie die JSON-Darstellung dieses Fehlers:

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

So beheben Sie diesen Fehler:

  1. Rufen Sie die Google API Console auf.
  2. Wählen Sie Ihr Projekt aus.
  3. Klicken Sie auf den Tab Kontingente.
  4. Fordern Sie ein zusätzliches Kontingent an. Weitere Informationen finden Sie unter Zusätzliche Kontingente anfordern.

Weitere Informationen zu Gmail-Beschränkungen finden Sie unter Nutzungslimits.

403-Fehler beheben: Ratenbegrenzung für Nutzer überschritten

Der Fehler userRateLimitExceeded gibt an, dass die Beschränkung pro Nutzer erreicht wurde. So sieht die JSON-Darstellung dieses Fehlers aus:

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

Zur Behebung dieses Fehlers sollten Sie Ihren Anwendungscode so optimieren, dass weniger Anfragen gestellt oder wiederholt werden. Informationen zum Wiederholen von Anfragen finden Sie unter Fehlgeschlagene Anfragen wiederholen.

Weitere Informationen zu Gmail-Beschränkungen finden Sie unter Nutzungslimits.

403-Fehler beheben: Ratenbegrenzung überschritten

Der Fehler rateLimitExceeded gibt an, dass der Nutzer die maximale Anfragerate der Gmail API erreicht hat. Dieses Limit variiert je nach Art der Anfragen. Im Folgenden sehen Sie die JSON-Darstellung dieses Fehlers:

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

Versuchen Sie fehlgeschlagene Anfragen noch einmal, um diesen Fehler zu beheben.

Weitere Informationen zu Gmail-Beschränkungen finden Sie unter Nutzungslimits.

403-Fehler beheben: Die App mit der ID {appId} kann in der Domain des authentifizierten Nutzers nicht verwendet werden

Ein domainPolicy-Fehler tritt auf, wenn die Richtlinie für die Domain des Nutzers den Zugriff auf Gmail durch Ihre Anwendung nicht zulässt. Im Folgenden sehen Sie die JSON-Darstellung dieses Fehlers:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Gmail apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Gmail apps."
  }
}

So beheben Sie diesen Fehler:

  1. Informieren Sie den Nutzer, dass Ihre App in der Domain nicht auf Gmail zugreifen kann.
  2. Weisen Sie den Nutzer an, sich an den Domainadministrator zu wenden, um Zugriff auf Ihre App anzufordern.

Fehler 429 beheben: Zu viele Anfragen

Der Fehler 429 „Zu viele Anfragen“ kann aufgrund von täglichen Limits pro Nutzer (einschließlich Sendebeschränkungen für E-Mails), Bandbreitenbeschränkungen oder Limits für gleichzeitige Anfragen pro Nutzer auftreten. Informationen zu den einzelnen Limits folgen. Jedes Limit kann jedoch durch Wiederholen fehlgeschlagener Anfragen oder durch Aufteilen der Verarbeitung auf mehrere Gmail-Konten aufgehoben werden. Die Limits pro Nutzer können aus irgendeinem Grund nicht erhöht werden. Weitere Informationen zu Limits finden Sie unter Nutzungslimits.

Beschränkungen für das Senden von E-Mails

Die Gmail API erzwingt die standardmäßigen täglichen Sendebeschränkungen für E-Mails. Diese Limits gelten für zahlende Google Workspace Nutzer und Nutzer von gmail.com, die eine Testversion nutzen. Weitere Informationen finden Sie im Hilfeartikel Gmail-Sendebeschränkungen in Google Workspace.

Diese Limits gelten pro Nutzer und werden von allen Clients des Nutzers geteilt, unabhängig davon, ob es sich um API-Clients, native Clients, Webclients oder SMTP-MSA handelt. Werden diese Limits überschritten, wird der HTTP-Fehler 429 Too Many Requests „Limit der Nutzerrate überschritten“ „(Senden von E-Mails)“ mit Zeit für den erneuten Versuch zurückgegeben. Beachten Sie, dass die Überschreitung der Tageslimits mehrere Stunden lang zu Fehlern dieser Art führen kann, bevor die Anfrage akzeptiert wird.

Die Pipeline für das Senden von E-Mails ist komplex: Wenn der Nutzer sein Kontingent überschreitet, kann es einige Minuten dauern, bis die API den Fehler 429 zurückgibt. Sie können also nicht davon ausgehen, dass die Antwort 200 bedeutet, dass die E-Mail erfolgreich gesendet wurde.

Bandbreitenlimits

Die API hat pro Nutzer Bandbreitenbeschränkungen für Uploads und Downloads, die denen von IMAP entsprechen, aber unabhängig davon sind. Diese Limits gelten für alle Gmail API-Clients eines bestimmten Nutzers.

Diese Beschränkungen gelten in der Regel nur in außergewöhnlichen oder missbräuchlichen Situationen. Wenn diese Limits überschritten werden, wird der HTTP-Fehler 429 Too Many Requests „Limit für Nutzer überschritten“ mit einer Zeit für den erneuten Versuch zurückgegeben. Beachten Sie, dass das Überschreiten der Tageslimits zu dieser Art von Fehlern für mehrere Stunden führen kann, bevor die Anfrage akzeptiert wird.

Gleichzeitige Requests

Die Gmail API erzwingt ein Limit für gleichzeitige Anfragen pro Nutzer (zusätzlich zur Ratenbegrenzung pro Nutzer). Dieses Limit gilt für alle Gmail API-Clients, die auf einen bestimmten Nutzer zugreifen, und sorgt dafür, dass kein API-Client das Postfach eines Gmail-Nutzers oder dessen Backend-Server überlastet.

Dieser Fehler kann auftreten, wenn viele parallele Anfragen für einen einzelnen Nutzer gestellt oder Batches mit einer großen Anzahl von Anfragen gesendet werden. Dieser Fehler kann ebenfalls ausgelöst werden, wenn viele unabhängige API-Clients gleichzeitig auf das Gmail-Postfach zugreifen. Wenn dieses Limit überschritten wird, wird der HTTP-Fehler 429 Too Many Requests „Too viele gleichzeitige Anfragen für Nutzer“ zurückgegeben.

Fehler 500 beheben: Backend-Fehler

Ein backendError tritt auf, wenn bei der Verarbeitung der Anfrage ein unerwarteter Fehler auftritt.

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

Versuchen Sie fehlgeschlagene Anfragen noch einmal, um diesen Fehler zu beheben. Die folgende Liste enthält die Fehler 500:

  • 502 Fehlerhaftes Gateway
  • 503 Dienst nicht verfügbar
  • 504 Gateway-Zeitüberschreitung

Fehlgeschlagene Anfragen wiederholen, um Fehler zu beheben

Sie können eine fehlgeschlagene Anfrage regelmäßig über einen längeren Zeitraum wiederholen, um Fehler im Zusammenhang mit Ratenbegrenzungen, Netzwerkvolumen oder Antwortzeit zu beheben. Beispielsweise können Sie eine fehlgeschlagene Anfrage nach einer Sekunde, dann nach zwei und dann nach vier Sekunden wiederholen. Diese Methode wird als exponentieller Backoff bezeichnet und dient dazu, die Bandbreitennutzung zu verbessern und den Durchsatz von Anfragen in gleichzeitigen Umgebungen zu maximieren.

Wiederholen Sie den Wiederholungszeitraum mindestens eine Sekunde nach dem Fehler.

Nutzungslimits ansehen oder ändern, Kontingent erhöhen

Wenn Sie die Nutzungslimits für Ihr Projekt aufrufen oder ändern bzw. eine Erhöhung Ihres Kontingents anfragen möchten, gehen Sie so vor:

  1. Wenn Sie für Ihr Projekt noch kein Rechnungskonto haben, erstellen Sie dieses.
  2. Rufen Sie in der API Console die Seite „Aktivierte APIs“ auf und wählen Sie eine API aus der Liste aus.
  3. Klicken Sie auf Kontingente, um die Einstellungen zum Kontingent aufzurufen und zu ändern. Klicken Sie auf Nutzung, um die Nutzungsstatistik einzusehen.

Batchanfragen

Die Verwendung von Batching wird empfohlen. Größere Batchgrößen lösen jedoch wahrscheinlich eine Ratenbegrenzung aus. Das Senden von Batches mit mehr als 50 Anfragen wird nicht empfohlen. Informationen zu Batchanfragen finden Sie unter Anfragen im Batch verarbeiten.