Fehler beheben.

Die Gmail API gibt zwei Arten 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.

Gmail-Apps sollten alle Fehler abfangen 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: Ungültige Anfrage

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

  • Ein erforderliches Feld oder ein erforderlicher Parameter wurde nicht angegeben.
  • Der angegebene Wert oder eine Kombination der angegebenen Felder ist ungültig.
  • Ungültiger Anhang.

Unten sehen Sie ein Beispiel für die 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 Ihren Code entsprechend an.

Fehler 401 „Ungültige Anmeldedaten“ beheben

Ein 401-Fehler weist darauf hin, 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 Aktualisierung von Tokens automatisch durchgeführt. Wenn dies fehlschlägt, leiten Sie den Nutzer durch den OAuth-Ablauf, wie unter App für Gmail autorisieren beschrieben.

Weitere Informationen zu 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, sehen Sie sich das Feld reason der zurückgegebenen JSON an. Dieser Fehler tritt in folgenden Situationen auf:

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

Weitere Informationen zu Gmail-Limits finden Sie unter Nutzungslimits.

403-Fehler beheben: Tageslimit überschritten

Ein dailyLimitExceeded-Fehler gibt an, dass das Kulanz-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. Zusätzliches Kontingent anfordern Weitere Informationen finden Sie unter Zusätzliche Kontingente anfordern.

Weitere Informationen zu Gmail-Limits finden Sie unter Nutzungslimits.

403-Fehler beheben: Nutzerbeschränkung überschritten

Ein userRateLimitExceeded-Fehler weist darauf hin, dass das Limit 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"
 }
}

Um diesen Fehler zu beheben, können Sie versuchen, Ihren Anwendungscode so zu optimieren, dass weniger Anfragen gesendet werden oder Anfragen wiederholt werden. Informationen zum Wiederholen von Anfragen finden Sie unter Fehler beheben, indem Sie fehlgeschlagene Anfragen wiederholen.

Weitere Informationen zu Gmail-Limits finden Sie unter Nutzungslimits.

403-Fehler „Rate limit exceeded“ beheben

Ein rateLimitExceeded-Fehler weist darauf hin, 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 Gmail-Limits finden Sie unter Nutzungslimits.

403-Fehler beheben: 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. Im Folgenden 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 die Domain Ihrer App keinen Zugriff auf Gmail erlaubt.
  2. Bitten Sie den Nutzer, sich an den Domainadministrator zu wenden, um Zugriff für Ihre App anzufordern.

429-Fehler beheben: Zu viele Anfragen

Der Fehler 429 „Too many requests“ (Zu viele Anfragen) kann aufgrund von täglichen Limits pro Nutzer (einschließlich Sendelimits für E-Mails), Bandbreitenlimits oder einem Limit für gleichzeitige Anfragen pro Nutzer auftreten. Informationen zu den einzelnen Limits folgen. Jedes Limit kann jedoch behoben werden, indem Sie entweder versuchen, fehlgeschlagene Anfragen noch einmal zu senden, oder die Verarbeitung auf mehrere Gmail-Konten aufteilen. Die Beschränkungen pro Nutzer können aus keinem Grund erhöht werden. Weitere Informationen zu Limits finden Sie unter Nutzungslimits.

Sendebeschränkungen für E-Mails

Die Gmail API erzwingt die standardmäßigen täglichen Sendelimits für E‑Mails. Diese Limits unterscheiden sich für zahlende Nutzer und Nutzer von Gmail-Testkonten. Informationen zu diesen Beschränkungen finden Sie unter Gmail-Sendebeschränkungen in .

Diese Limits gelten pro Nutzer und werden von allen Clients des Nutzers gemeinsam genutzt, unabhängig davon, ob es sich um API-Clients, native Clients/Webclients oder SMTP MSA handelt. Wenn diese Beschränkungen überschritten werden, wird der HTTP-Fehler 429 Too Many Requests „User-rate limit exceeded“ (Mail sending) (Nutzer-Ratenbeschränkung überschritten (Mailversand)) mit der Zeit für den erneuten Versuch zurückgegeben. Wenn die Tageslimits überschritten werden, kann es mehrere Stunden dauern, bis die Anfrage akzeptiert wird.

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

Bandbreitenbeschränkungen

Für die API gelten Bandbreitenbeschränkungen für Uploads und Downloads pro Nutzer, die mit IMAP identisch sind, aber unabhängig davon gelten. Diese Limits gelten für alle Gmail API-Clients für einen bestimmten Nutzer.

Diese Grenzwerte werden in der Regel nur in Ausnahmefällen oder bei Missbrauch erreicht. Wenn diese Limits überschritten werden, wird der HTTP-Fehler 429 Too Many Requests „User-rate limit exceeded“ (Ratenbegrenzung für Nutzer überschritten) mit einer Zeit für den erneuten Versuch zurückgegeben. Wenn die Tageslimits überschritten werden, kann es mehrere Stunden dauern, bis die Anfrage akzeptiert wird. In dieser Zeit können diese Fehlertypen auftreten.

Gleichzeitige Anfragen

Die Gmail API erzwingt ein Limit für gleichzeitige Anfragen pro Nutzer (zusätzlich zum Ratenlimit pro Nutzer). Dieses Limit gilt für alle Gmail API-Clients, die auf einen bestimmten Nutzer zugreifen, und soll verhindern, dass ein API-Client das Gmail-Postfach eines Nutzers oder den zugehörigen Backend-Server überlastet.

Dieser Fehler kann auftreten, wenn Sie viele parallele Anfragen für einen einzelnen Nutzer stellen oder Batches mit einer großen Anzahl von Anfragen senden. Eine große Anzahl unabhängiger API-Clients, die gleichzeitig auf das Gmail-Nutzerpostfach zugreifen, kann ebenfalls diesen Fehler auslösen. Wenn dieses Limit überschritten wird, wird der HTTP-Fehler 429 Too Many Requests „Too many concurrent requests for user“ (Zu viele gleichzeitige Anfragen für den 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"
 }
}

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

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

Fehler beheben, indem Sie fehlgeschlagene Anfragen wiederholen

Sie können eine fehlgeschlagene Anfrage über einen immer länger werdenden Zeitraum periodisch wiederholen, um Fehler im Zusammenhang mit Ratenbeschränkungen, Netzwerkvolumen oder Antwortzeit zu beheben. Sie können beispielsweise eine fehlgeschlagene Anfrage nach einer Sekunde, dann nach zwei Sekunden und dann nach vier Sekunden noch einmal senden. Diese Methode wird als exponentieller Backoff bezeichnet. Sie wird verwendet, um die Bandbreitennutzung zu verbessern und den Durchsatz von Anfragen in Umgebungen mit Gleichzeitigkeit zu maximieren.

Wiederholungszeiträume müssen mindestens eine Sekunde nach dem Fehler beginnen.

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“ 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 Batching wird empfohlen. Bei größeren Batchgrößen wird jedoch wahrscheinlich eine Ratenbegrenzung ausgelöst. Das Senden von Batches mit mehr als 50 Anfragen wird nicht empfohlen. Informationen zum Batchverarbeiten von Anfragen finden Sie unter Anfragen im Batch verarbeiten.