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.

Ihre Gmail-App sollte alle Fehler abfangen und verarbeiten, die bei der Verwendung der REST API auftreten. In dieser Anleitung finden Sie Informationen zur Behebung bestimmter Gmail API-Fehler.

Zusammenfassung der HTTP-Statuscodes

400er-Fehler

Diese Fehler bedeuten, dass die Anfrage einen Fehler enthält, häufig aufgrund eines fehlenden erforderlichen Parameters.

badRequest

Dieser Fehler kann durch eines der folgenden Probleme in Ihrem Code verursacht werden:

• Ein Pflichtfeld oder ein erforderlicher Parameter fehlt.
• Ein angegebener Wert oder eine Kombination von Feldern ist ungültig.
• Der Anhang ist ungültig.

Das folgende JSON-Beispiel zeigt eine 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.

401-Fehler

Diese Fehler bedeuten, dass die Anfrage kein gültiges Zugriffstoken enthält.

authError

Dieser Fehler tritt auf, wenn das von Ihnen verwendete Zugriffstoken abgelaufen oder ungültig ist. Auch eine fehlende Autorisierung für die angeforderten Bereiche kann diesen Fehler verursachen. Das folgende JSON-Beispiel zeigt eine 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 das fehlschlägt, leiten Sie den Nutzer durch den OAuth-Ablauf, wie unter Authentifizierung und Autorisierung beschrieben.

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

403-Fehler

Diese Fehler treten auf, wenn Sie ein Nutzungslimit überschreiten oder der Nutzer nicht die richtigen Berechtigungen hat. Um die Ursache zu ermitteln, sehen Sie sich das Feld reason der zurückgegebenen JSON-Datei an. Dieser Fehler tritt in den folgenden Situationen auf:

• Ihre App kann nicht in der Domain des authentifizierten Nutzers verwendet werden.
• Das Projekt hat das Tageslimit überschritten.
• Der Nutzer hat die Ratenbegrenzung überschritten.
• Das Projekt hat die Ratenbegrenzung überschritten.

Weitere Informationen finden Sie unter Nutzungslimits.

dailyLimitExceeded

Dieser Fehler tritt auf, wenn Ihr Projekt das API-Limit erreicht. Das folgende JSON-Beispiel zeigt eine Darstellung dieses Fehlers:

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

Dieser Fehler tritt auf, wenn der Anwendungsbesitzer ein Kontingentlimit festlegt, um die Nutzung einer bestimmten Ressource zu begrenzen. Erhöhen Sie das Kontingent im Google Cloud-Projekt, um diesen Fehler zu beheben. Weitere Informationen finden Sie unter Kontingentlimits verwalten.

domainPolicy

Dieser Fehler tritt auf, wenn die Richtlinie für die Domain des Nutzers den Zugriff Ihrer App auf Gmail nicht zulässt. Die folgende JSON-Datei ist die 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."
  }
}

Versuchen Sie Folgendes, um diesen Fehler zu beheben:

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

rateLimitExceeded

Dieser Fehler weist darauf hin, dass der Nutzer die maximale Anforderungsrate für die Gmail API erreicht hat. Dieses Limit variiert je nach Anfragetyp. Das folgende JSON-Beispiel zeigt eine Darstellung dieses Fehlers:

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

Versuchen Sie Folgendes, um diesen Fehler zu beheben:

• Kontingenterhöhung anfordern
• Verwenden Sie den exponentiellen Backoff, um die Anfrage noch einmal zu senden.

userRateLimitExceeded

Dieser Fehler tritt auf, wenn eine Anfrage das Limit pro Nutzer erreicht. Das folgende JSON-Beispiel zeigt eine 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, optimieren Sie den Anwendungscode, sodass weniger Anfragen gesendet werden, oder verwenden Sie exponentiellen Backoff, um die Anfrage zu wiederholen.

429-Fehler

Ein 429-Fehler („Too many requests“) kann aufgrund von täglichen Limits pro Nutzer (einschließlich Sendebeschränkungen für E-Mails), Bandbreitenlimits oder einem Limit für gleichzeitige Anfragen pro Nutzer auftreten. Informationen zu den einzelnen Limits finden Sie unten. Jedes Limit kann jedoch behoben werden, indem Sie entweder fehlgeschlagene Anfragen noch einmal senden oder die Verarbeitung auf mehrere Gmail-Konten aufteilen.

Die Limits pro Nutzer können nicht 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 Google Workspace-Nutzer und Nutzer von Gmail-Testkonten. Informationen zu diesen Beschränkungen finden Sie unter 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, integrierte Clients, Webclients oder SMTP MSA handelt. Wenn Sie diese Beschränkungen überschreiten, gibt die API den HTTP-Fehler 429 „Too many requests: User-rate limit exceeded (Mail sending)“ (Zu viele Anfragen: Ratenbegrenzung für Nutzer überschritten (E-Mail-Versand)) mit einer Wiederholungszeit zurück. Wenn Sie die Tageslimits überschreiten, kann es mehrere Stunden dauern, bis der Server die Anfrage akzeptiert.

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

Bandbreitenbeschränkungen

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

Nutzer stoßen in der Regel nur in Ausnahmefällen oder bei missbräuchlicher Nutzung auf diese Limits. Wenn Sie diese Limits überschreiten, gibt die API den HTTP-Fehler 429 „Too many requests: User-rate limit exceeded“ (Zu viele Anfragen: Nutzer-Ratenbegrenzung überschritten) mit einer Wiederholungszeit zurück. Wenn Sie die Tageslimits überschreiten, kann es mehrere Stunden dauern, bis der Server die Anfrage akzeptiert.

Gleichzeitige Anfragen

Für die Gmail API gilt 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 Nutzer zugreifen, und soll verhindern, dass ein API-Client das Gmail-Postfach eines Nutzers oder den zugehörigen Back-End-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. Eine große Anzahl unabhängiger API-Clients, die gleichzeitig auf das Gmail-Nutzerpostfach zugreifen, kann ebenfalls diesen Fehler auslösen. Wenn Sie dieses Limit überschreiten, gibt die API den HTTP-Fehler 429 „Too many requests: Too many concurrent requests for user“ (Zu viele Anfragen: Zu viele gleichzeitige Anfragen für Nutzer) zurück.

Fehler 500, 502, 503, 504

Diese Fehler treten auf, wenn beim Verarbeiten der Anfrage ein unerwarteter Serverfehler auftritt. Diese Fehler können durch verschiedene Probleme verursacht werden, z. B. wenn sich der Zeitpunkt einer Anfrage mit dem einer anderen Anfrage überschneidet oder wenn eine Anfrage für eine nicht unterstützte Aktion gestellt wird, z. B. wenn versucht wird, Berechtigungen für eine einzelne Seite in Google Sites anstelle der gesamten Website zu aktualisieren.

Im Folgenden finden Sie eine Liste der 5xx-Fehler:

• 500 Backend-Fehler
• 502 Fehlerhaftes Gateway
• 503 – Dienst nicht verfügbar
• 504 Gateway-Zeitüberschreitung

backendError

Dieser Fehler tritt auf, wenn bei der Verarbeitung der Anfrage ein unerwarteter Fehler auftritt. Das folgende JSON-Beispiel zeigt eine Darstellung dieses Fehlers:

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

Verwenden Sie exponentiellen Backoff, um die Anfrage zu wiederholen.

Fehler durch Wiederholen fehlgeschlagener Anfragen beheben

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 sollten mindestens eine Sekunde nach dem Fehler beginnen.

Kontingentlimits verwalten

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.

Weitere Informationen finden Sie unter Kontingente aufrufen und verwalten.

Batchanfragen

Batchanfragen können die Leistung verbessern, aber größere Batchgrößen können zu Ratenbeschränkungen führen. Senden Sie keine Batches mit mehr als 50 Anfragen. Informationen zum Batchverarbeiten von Anfragen finden Sie unter Batchanfragen.

Weitere Informationen

• Tipps zur Leistung
• Probleme bei der Authentifizierung und Autorisierung beheben