Die Calendar API gibt zwei Ebenen mit Fehlerinformationen zurück:
- HTTP-Fehlercodes und -Meldungen im Header
- Ein JSON-Objekt im Antworttext mit zusätzlichen Details, anhand dessen Sie bestimmen können, wie der Fehler behoben werden soll.
Der Rest dieser Seite enthält eine Referenz zu Kalenderfehlern sowie eine Anleitung zur Behebung dieser Fehler in Ihrer Anwendung.
Exponentiellen Backoff implementieren
In der Cloud APIs-Dokumentation wird der exponentielle Backoff und seine Verwendung mit den Google APIs gut erklärt.
Fehler und empfohlene Maßnahmen
Dieser Abschnitt enthält die vollständige JSON-Darstellung jedes aufgelisteten Fehlers sowie empfohlene Maßnahmen zur Behebung.
400: Ungültige Anfrage
Nutzerfehler. Dies kann bedeuten, dass ein erforderliches Feld oder ein erforderlicher Parameter nicht angegeben wurde, der angegebene Wert ungültig ist oder die Kombination der angegebenen Felder ungültig ist.
{
"error": {
"errors": [
{
"domain": "calendar",
"reason": "timeRangeEmpty",
"message": "The specified time range is empty.",
"locationType": "parameter",
"location": "timeMax",
}
],
"code": 400,
"message": "The specified time range is empty."
}
}
Empfohlene Maßnahme:Da dies ein dauerhafter Fehler ist, versuchen Sie es nicht noch einmal. Lesen Sie stattdessen die Fehlermeldung und ändern Sie Ihre Anfrage entsprechend.
401: Ungültige Anmeldedaten
Ungültiger Autorisierungsheader. Das von Ihnen verwendete Zugriffstoken ist entweder abgelaufen oder ungültig.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "authError",
"message": "Invalid Credentials",
"locationType": "header",
"location": "Authorization",
}
],
"code": 401,
"message": "Invalid Credentials"
}
}
Empfohlene Maßnahmen:
- Rufen Sie mithilfe des langlebigen Aktualisierungstokens ein neues Zugriffstoken ab.
- Wenn das nicht funktioniert, leite den Nutzer durch den OAuth-Ablauf, wie unter Anfragen mit OAuth 2.0 autorisieren beschrieben.
- Wenn Sie diese Meldung für ein Dienstkonto sehen, prüfen Sie, ob Sie alle Schritte auf der Dienstkontoseite erfolgreich ausgeführt haben.
403: Begrenzung der Nutzerrate überschritten
Eines der Limits der Developer Console wurde erreicht.
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "userRateLimitExceeded",
"message": "User Rate Limit Exceeded"
}
],
"code": 403,
"message": "User Rate Limit Exceeded"
}
}
Empfohlene Maßnahmen:
- Ihre Anwendung muss den Best Practices im Abschnitt Kontingente verwalten entsprechen.
- Erhöhen Sie das Kontingent pro Nutzer im Developer Console-Projekt.
- Wenn ein Nutzer viele Anfragen im Namen vieler Nutzer eines Google Workspace-Kontos sendet, sollten Sie ein Dienstkonto mit domainweiter Delegierung verwenden und den Parameter
quotaUser
festlegen. - Verwenden Sie den exponentiellen Backoff.
403: Ratenbegrenzung überschritten
Der Nutzer hat die maximale Anfragerate der Google Calendar API pro Kalender oder pro authentifiziertem Nutzer erreicht.
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "rateLimitExceeded",
"message": "Rate Limit Exceeded"
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Empfohlene Maßnahme:rateLimitExceeded
-Fehler können entweder die Fehlercodes 403 oder 429 zurückgeben. Derzeit sind sie funktional ähnlich und sollten über den exponentiellen Backoff auf die gleiche Weise beantwortet werden.
Achten Sie außerdem darauf, dass Ihre Anwendung den Best Practices zum Verwalten von Kontingenten entspricht.
403: Nutzungslimits für Kalender überschritten
Der Nutzer hat eine der Limits für Google Kalender erreicht, um Google-Nutzer und -Infrastruktur vor missbräuchlichem Verhalten zu schützen.
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Calendar usage limits exceeded.",
"reason": "quotaExceeded"
}
],
"code": 403,
"message": "Calendar usage limits exceeded."
}
}
Empfohlene Maßnahmen:
- Weitere Informationen zu den Nutzungslimits für Google Kalender finden Sie in der Hilfe für Google Workspace-Administratoren.
403: Unzulässig für Nicht-Organisator
Die Anfrage zur Terminaktualisierung versucht, eines der freigegebenen Ereignisattribute in einer Kopie festzulegen, die nicht dem Organisator gehört. Gemeinsame Attribute (z. B. guestsCanInviteOthers
, guestsCanModify
oder guestsCanSeeOtherGuests
) können nur vom Organisator festgelegt werden.
{
"error": {
"errors": [
{
"domain": "calendar",
"reason": "forbiddenForNonOrganizer",
"message": "Shared properties can only be changed by the organizer of the event."
}
],
"code": 403,
"message": "Shared properties can only be changed by the organizer of the event."
}
}
Empfohlene Maßnahmen:
- Wenn Sie Events: insert, Events: import oder Events: update verwenden und keine freigegebenen Attribute enthalten, entspricht dies dem Versuch, diese auf die Standardwerte festzulegen. Verwenden Sie stattdessen Ereignisse: patch.
- Hat Ihre Anfrage gemeinsame Attribute, ändern Sie diese nur, wenn Sie die Kopie des Organisators aktualisieren.
404: Nicht gefunden
Die angegebene Ressource wurde nicht gefunden. Dies kann in mehreren Fällen passieren. Beispiele:
- wenn die angeforderte Ressource (mit der angegebenen ID) nie existiert hat.
beim Zugriff auf einen Kalender, auf den der Nutzer nicht zugreifen kann
{ "error": { "errors": [ { "domain": "global", "reason": "notFound", "message": "Not Found" } ], "code": 404, "message": "Nicht gefunden" } }
Empfohlene Maßnahme:Verwenden Sie den exponentiellen Backoff.
409: Die angeforderte ID ist bereits vorhanden
Eine Instanz mit der angegebenen ID ist bereits im Speicher vorhanden.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "duplicate",
"message": "The requested identifier already exists."
}
],
"code": 409,
"message": "The requested identifier already exists."
}
}
Empfohlene Maßnahme:Generieren Sie eine neue ID, wenn Sie eine neue Instanz erstellen möchten. Andernfalls verwenden Sie den update-Methodenaufruf.
410: Verschwunden
Die Parameter syncToken
oder updatedMin
sind nicht mehr gültig. Dieser Fehler kann auch auftreten, wenn eine Anfrage versucht, ein bereits gelöschtes Ereignis zu löschen.
{
"error": {
"errors": [
{
"domain": "calendar",
"reason": "fullSyncRequired",
"message": "Sync token is no longer valid, a full sync is required.",
"locationType": "parameter",
"location": "syncToken",
}
],
"code": 410,
"message": "Sync token is no longer valid, a full sync is required."
}
}
oder
{
"error": {
"errors": [
{
"domain": "calendar",
"reason": "updatedMinTooLongAgo",
"message": "The requested minimum modification time lies too far in the past.",
"locationType": "parameter",
"location": "updatedMin",
}
],
"code": 410,
"message": "The requested minimum modification time lies too far in the past."
}
}
oder
{
"error": {
"errors": [
{
"domain": "global",
"reason": "deleted",
"message": "Resource has been deleted"
}
],
"code": 410,
"message": "Resource has been deleted"
}
}
Empfohlene Maßnahme: Löschen Sie für die Parameter syncToken
oder updatedMin
den Speicher und führen Sie eine neue Synchronisierung durch. Weitere Informationen finden Sie unter Ressourcen effizient synchronisieren.
Für bereits gelöschte Ereignisse sind keine weiteren Maßnahmen erforderlich.
412: Vorbedingung fehlgeschlagen
Das im If-match-Header angegebene ETag entspricht nicht mehr dem aktuellen ETag der Ressource.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "conditionNotMet",
"message": "Precondition Failed",
"locationType": "header",
"location": "If-Match",
}
],
"code": 412,
"message": "Precondition Failed"
}
}
Vorgeschlagene Maßnahme: Rufen Sie die Entität noch einmal ab und wenden Sie die Änderungen noch einmal an. Weitere Informationen finden Sie unter Bestimmte Versionen von Ressourcen abrufen.
429: Zu viele Anfragen
Ein rateLimitExceeded
-Fehler tritt auf, wenn der Nutzer zu viele Anfragen in einem bestimmten Zeitraum gesendet hat.
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "rateLimitExceeded",
"message": "Rate Limit Exceeded"
}
],
"code": 429,
"message": "Rate Limit Exceeded"
}
}
Empfohlene Maßnahme:rateLimitExceeded
-Fehler können entweder die Fehlercodes 403 oder 429 zurückgeben. Derzeit sind sie funktional ähnlich und sollten über den exponentiellen Backoff auf die gleiche Weise beantwortet werden.
Achten Sie außerdem darauf, dass Ihre Anwendung den Best Practices zum Verwalten von Kontingenten entspricht.
500: Back-End-Fehler
Beim Verarbeiten der Anfrage ist ein unerwarteter Fehler aufgetreten.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
Empfohlene Maßnahme:Verwenden Sie den exponentiellen Backoff.