Fehler beheben.

Die Gmail API gibt zwei Fehlerebenen zurück:

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

Gmail-Apps sollten alle Fehler abfangen und verarbeiten, die bei der Verwendung der REST API auftreten können. In diesem Leitfaden finden Sie Anleitungen zur Behebung bestimmter API-Fehler.

400-Fehler beheben: Ungültige Anfrage

Dieser Fehler kann durch folgende Fehler in Ihrem Code verursacht werden:

  • Ein Pflichtfeld oder ein Pflichtparameter wurde nicht angegeben.
  • Der angegebene Wert oder eine Kombination der angegebenen Felder ist ungültig.
  • Ungültiger Anhang.

Im Folgenden finden Sie eine Beispiel-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, prüfen Sie das Feld message und passen Sie den Code entsprechend an.

401-Fehler beheben: Ungültige Anmeldedaten

Ein 401-Fehler weist darauf hin, dass das 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 das Token automatisch aktualisiert. Wenn das nicht funktioniert, bitte den Nutzer, den OAuth-Ablauf wie unter App mit Gmail autorisieren beschrieben durchzuführen.

Weitere Informationen zu den Gmail-Limits finden Sie unter Nutzungslimits.

403-Fehler beheben: Nutzungslimit überschritten

Ein Fehler 403 tritt auf, wenn ein Nutzungslimit überschritten wurde oder der Nutzer nicht die richtigen Berechtigungen hat. Um den genauen Fehlertyp zu ermitteln, prüfen Sie das Feld reason der zurückgegebenen JSON-Datei. Dieser Fehler tritt in folgenden Situationen auf:

  • Das Tageslimit wurde überschritten.
  • Die Ratenbegrenzung für Nutzer wurde überschritten.
  • Die Ratenbegrenzung für das Projekt wurde überschritten.
  • Ihre App kann nicht in der Domain des authentifizierten Nutzers verwendet werden.

Weitere Informationen zu den Gmail-Limits finden Sie unter Nutzungslimits.

403-Fehler beheben: Tageslimit überschritten

Ein dailyLimitExceeded-Fehler gibt an, dass das Limit für die kostenlose API 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 den Gmail-Limits finden Sie unter Nutzungslimits.

403-Fehler beheben: Nutzerratenlimit überschritten

Ein Fehler vom Typ userRateLimitExceeded gibt an, dass die Begrenzung pro Nutzer erreicht wurde. Im Folgenden sehen Sie die JSON-Darstellung dieses Fehlers:

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

Optimieren Sie Ihren Anwendungscode, um weniger Anfragen zu stellen oder Anfragen noch einmal zu versuchen, um diesen Fehler zu beheben. Informationen zum Wiederholen von Anfragen finden Sie unter Fehlgeschlagene Anfragen wiederholen.

Weitere Informationen zu den Gmail-Limits finden Sie unter Nutzungslimits.

403-Fehler beheben: Ratenlimit überschritten

Ein rateLimitExceeded-Fehler 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"
 }
}

Wiederholen Sie fehlgeschlagene Anfragen, um diesen Fehler zu beheben.

Weitere Informationen zu den Gmail-Limits finden Sie unter Nutzungslimits.

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

Ein domainPolicy-Fehler tritt auf, wenn die Richtlinie für die Domain des Nutzers den Zugriff auf Gmail durch Ihre App nicht zulässt. Unten finden 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 aufgrund der Domain nicht auf Gmail zugreifen kann.
  2. Bitten Sie den Nutzer, sich an den Domainadministrator zu wenden, um Zugriff für Ihre App anzufordern.

429-Fehler beheben: Zu viele Anfragen

Ein Fehler 429 „Zu viele Anfragen“ kann aufgrund von täglichen Limits pro Nutzer (einschließlich Limits für das Senden von E-Mails), Bandbreitenlimits oder Limits für gleichzeitige Anfragen pro Nutzer auftreten. Nachfolgend finden Sie Informationen zu den einzelnen Limits. Jedes Limit kann jedoch entweder durch Wiederholen fehlgeschlagener Anfragen oder durch Aufteilen der Verarbeitung auf mehrere Gmail-Konten behoben werden. Die Limits pro Nutzer können aus keinem Grund erhöht werden. Weitere Informationen zu Limits finden Sie unter Nutzungslimits.

Beschränkungen beim Senden von E-Mails

Die Gmail API erzwingt die standardmäßigen täglichen Limits für das Senden von E-Mails. Diese Limits unterscheiden sich für zahlende Google Workspace Nutzer und Nutzer der kostenlosen Testversion von gmail.com. Weitere Informationen zu diesen Limits finden Sie im Hilfeartikel Gmail-Sendebeschränkungen in Google Workspace.

Diese Limits gelten pro Nutzer und werden von allen Clients des Nutzers gemeinsam genutzt, unabhängig davon, ob es sich um API-Clients, native/Web-Clients oder SMTP-MSAs handelt. Wenn diese Limits überschritten werden, wird der Fehler „HTTP 429 Too Many Requests „User-rate limit exceeded“ (Mail sending)“ (HTTP 429 Too Many Requests „Nutzerrate überschritten“ (E-Mail-Versand)) mit einer Zeitspanne zurückgegeben, nach der ein neuer Versuch unternommen werden kann. Wenn die Tageslimits überschritten werden, kann es mehrere Stunden dauern, bis die Anfrage akzeptiert wird.

Die Pipeline zum Senden von E-Mails ist komplex: Sobald der Nutzer sein Kontingent überschritten hat, kann es einige Minuten dauern, bis die API 429-Fehlerantworten zurückgibt. Sie können also nicht davon ausgehen, dass eine Antwort mit 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 Grenzwerte werden in der Regel nur in Ausnahmefällen oder bei Missbrauch erreicht. Wenn diese Limits überschritten werden, wird der Fehler HTTP 429 Too Many Requests „User-rate limit exceeded“ (Nutzer-Taktbegrenzung überschritten) mit einer Zeitspanne für einen erneuten Versuch zurückgegeben. Wenn die täglichen Limits überschritten werden, kann es mehrere Stunden dauern, bis die Anfrage akzeptiert wird.

Gleichzeitige Anfragen

Die Gmail API erzwingt zusätzlich zur Ratenbegrenzung pro Nutzer eine Begrenzung für gleichzeitige Anfragen pro Nutzer. Dieses Limit gilt für alle Gmail API-Clients, die auf einen bestimmten Nutzer zugreifen. So wird verhindert, dass ein API-Client ein Gmail-Postfach oder den zugehörigen Backend-Server überlastet.

Wenn Sie viele parallele Anfragen für einen einzelnen Nutzer stellen oder Batches mit einer großen Anzahl von Anfragen senden, kann dieser Fehler auftreten. Auch eine große Anzahl unabhängiger API-Clients, die gleichzeitig auf das Gmail-Nutzerpostfach zugreifen, kann diesen Fehler auslösen. Wird dieses Limit überschritten, wird der Fehler „HTTP 429 Too Many RequestsToo many concurrent requests for user“ (Zu viele gleichzeitige Anfragen für Nutzer) zurückgegeben.

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

Wiederholen Sie fehlgeschlagene Anfragen, um diesen Fehler zu beheben. Im Folgenden finden Sie eine Liste von 500er-Fehlern:

  • 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 in regelmäßigen Abständen über einen immer länger werdenden Zeitraum wiederholen, um Fehler im Zusammenhang mit Ratenlimits, Netzwerkvolumen oder Antwortzeit zu beheben. So können Sie beispielsweise eine fehlgeschlagene Anfrage nach einer, zwei und vier Sekunden noch einmal versuchen. Diese Methode wird als exponentielles Backoff bezeichnet und dient dazu, die Bandbreitennutzung zu verbessern und den Durchsatz von Anfragen in Umgebungen mit Gleichzeitigkeit zu maximieren.

Starten Sie die Wiederholungsintervalle mindestens eine Sekunde nach dem Fehler.

Nutzungslimits aufrufen 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“ in der API-Bibliothek 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 einzublenden.

Batchanfragen

Die Verwendung von Batches wird empfohlen. Bei größeren Batchgrößen wird jedoch wahrscheinlich die Ratenbegrenzung ausgelöst. Das Senden von Batches mit mehr als 50 Anfragen wird nicht empfohlen. Informationen zum Senden von Batchanfragen finden Sie unter Anfragen im Batch verarbeiten.