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 beheben, die bei der Verwendung der REST API auftreten können. In dieser Anleitung erfahren Sie, wie Sie bestimmte Gmail API-Fehler beheben.

Zusammenfassung der HTTP-Statuscodes

Fehlercode	Beschreibung
200 - OK	Die Anfrage war erfolgreich. Dies ist die Standardantwort für erfolgreiche HTTP-Anfragen.
400 - Bad Request	Die Anfrage kann aufgrund eines Clientfehlers in der Anfrage nicht ausgeführt werden.
401 - Unauthorized	Die Anfrage enthält ungültige Anmeldedaten.
403 - Forbidden	Die Anfrage wurde empfangen und verstanden, aber der Nutzer hat keine Berechtigung, sie auszuführen.
404 - Not Found	Die angeforderte Seite wurde nicht gefunden.
429 - Too Many Requests	Zu viele Anfragen an die API.
500, 502, 503, 504 - Server Errors	Beim Verarbeiten der Anfrage ist ein unerwarteter Fehler aufgetreten.

400-Fehler

Diese Fehler bedeuten, dass die Anfrage einen Fehler enthält, oft aufgrund eines fehlenden Pflichtparameters.

badRequest

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

• Ein Pflichtfeld oder -parameter wurde nicht angegeben.
• Der angegebene Wert oder eine Kombination aus angegebenen Feldern ist ungültig.
• Der Anhang ist ungültig.

Hinweis: Diese Liste ist nicht vollständig. Auch andere Fälle können einen 400-Fehler verursachen.

Das folgende JSON-Beispiel ist 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."
  }
}

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

401-Fehler

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

authError

Dieser Fehler tritt auf, wenn das verwendete Zugriffstoken abgelaufen oder ungültig ist. Dieser Fehler kann auch durch fehlende Autorisierung für die angeforderten Bereiche verursacht werden. Das folgende JSON-Beispiel ist 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 nicht funktioniert, leiten Sie den Nutzer durch den OAuth-Ablauf, wie unter Authentifizierung und Autorisierung beschrieben.

Weitere Informationen zu den Gmail-Limits finden Sie unter Nutzungs limits.

403-Fehler

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

• Ihre App kann nicht in der Domain des authentifizierten Nutzers verwendet werden.
• Das Tageslimit wurde überschritten.
• Das Nutzerlimit wurde überschritten.
• Das Projektlimit wurde überschritten.

Weitere Informationen finden Sie unter Nutzungslimits.

dailyLimitExceeded

Dieser Fehler tritt auf, wenn das API-Limit für Ihr Projekt erreicht wurde. Das folgende JSON-Beispiel ist eine Darstellung dieses Fehlers:

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

Dieser Fehler wird angezeigt, wenn der Inhaber der Anwendung ein Kontingentlimit festgelegt hat, 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 Kontingent limits verwalten.

domainPolicy

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

So beheben Sie diesen Fehler:

1. Informieren Sie den Nutzer, dass die Domain den Zugriff Ihrer App auf Gmail nicht zulässt.
2. Bitten Sie den Nutzer, sich an seinen Domainadministrator zu wenden und Zugriff für Ihre App anzufordern.

rateLimitExceeded

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

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

So beheben Sie diesen Fehler:

• Fordern Sie eine Kontingenterhöhung an.
• Wiederholen Sie die Anfrage mit exponentiellem Backoff.

userRateLimitExceeded

Dieser Fehler tritt auf, wenn das Limit pro Nutzer erreicht wurde. Das folgende JSON-Beispiel ist eine 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 wiederholen Sie die Anfrage mit exponentiellem Backoff, um diesen Fehler zu beheben.

429-Fehler

Ein 429-Fehler („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 finden Sie unten. Jedes Limit kann jedoch entweder durch Wiederholen fehlgeschlagener Anfragen oder durch Aufteilen der Verarbeitung auf mehrere Gmail-Konten behoben werden.

Limits pro Nutzer können aus keinem Grund erhöht werden. Weitere Informationen zu Limits finden Sie unter Nutzungslimits.

Sendelimits 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 der Gmail-Testversion (gmail.com). Informationen zu diesen Limits 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 diese Limits überschritten werden, wird ein HTTP-429-Fehler („Zu viele Anfragen: Nutzerlimit überschritten (E-Mail-Versand)“) mit einer Zeit für die Wiederholung zurückgegeben. Wenn die Tageslimits überschritten werden, können diese Fehler mehrere Stunden lang auftreten, bevor die Anfrage akzeptiert wird.

Die Pipeline für den E-Mail-Versand ist komplex. Wenn der Nutzer sein Kontingent überschreitet, kann es einige 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.

Bandbreitenlimits

Die API hat Bandbreitenlimits für Uploads und Downloads pro Nutzer, die mit IMAP identisch sind, aber unabhängig davon gelten. Diese Limits werden von allen Gmail API-Clients für einen Nutzer gemeinsam genutzt.

Diese Limits werden in der Regel nur in Ausnahmefällen oder bei Missbrauch erreicht. Wenn diese Limits überschritten werden, wird ein HTTP-429-Fehler („Zu viele Anfragen: Nutzerlimit überschritten“) mit einer Zeit für die Wiederholung zurückgegeben. Wenn die Tageslimits überschritten werden, können diese Fehler mehrere Stunden lang auftreten, bevor die Anfrage akzeptiert wird.

Gleichzeitige Anfragen

Die Gmail API erzwingt ein Limit für gleichzeitige Anfragen pro Nutzer (zusätzlich zum Ratenlimit pro Nutzer). Dieses Limit wird von allen Gmail API-Clients gemeinsam genutzt, die auf einen Nutzer zugreifen. So wird verhindert, dass ein API-Client das Gmail-Postfach eines Nutzers oder den zugehörigen 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. Auch wenn viele unabhängige API-Clients gleichzeitig auf das Gmail-Postfach eines Nutzers zugreifen, kann dieser Fehler auftreten. Wenn dieses Limit überschritten wird, wird ein HTTP-429-Fehler („Zu viele Anfragen: Zu viele gleichzeitige Anfragen für Nutzer“) zurückgegeben.

500-, 502-, 503- und 504-Fehler

Diese Fehler treten auf, wenn beim Verarbeiten der Anfrage ein unerwarteter Serverfehler auftritt. Verschiedene Probleme können diese Fehler verursachen, z. B. wenn sich die Zeitplanung einer Anfrage mit einer anderen Anfrage überschneidet oder wenn eine nicht unterstützte Aktion angefordert 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 beim Verarbeiten der Anfrage ein unerwarteter Fehler auftritt. Das folgende JSON-Beispiel ist eine Darstellung dieses Fehlers:

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

Wiederholen Sie die Anfrage mit exponentiellem Backoff, um diesen Fehler zu beheben.

Fehlgeschlagene Anfragen wiederholen, um Fehler zu beheben

Sie können eine fehlgeschlagene Anfrage in immer größeren Zeitabständen wiederholen, um Fehler im Zusammenhang mit Ratenlimits, Netzwerkvolumen oder Antwortzeit zu beheben. Sie können beispielsweise eine fehlgeschlagene Anfrage nach einer Sekunde, dann nach zwei Sekunden 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 Umgebungen mit Gleichzeitigkeit zu maximieren.

Beginnen Sie die Wiederholungszeiträume mindestens eine Sekunde nach dem Fehler.

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

Die Verwendung von Batchanfragen wird empfohlen. Bei größeren Batches ist jedoch mit Ratenbegrenzungen zu rechnen. Das Senden von Batches mit mehr als 50 Anfragen wird nicht empfohlen. Informationen zum Batching von Anfragen finden Sie unter Batch anfragen.

Weitere Informationen

• Bessere Leistung
• Probleme mit Authentifizierung und Autorisierung beheben