Obsługa błędów interfejsu API

Interfejs Kalendarza Google API zwraca 2 poziomy informacji o błędach:

  • kody błędów HTTP i komunikaty w nagłówku;
  • obiekt JSON w treści odpowiedzi z dodatkowymi informacjami, które mogą pomóc w określeniu, jak postępować w przypadku błędu.

W pozostałej części tej strony znajdziesz informacje o błędach Kalendarza oraz wskazówki, jak sobie z nimi radzić w aplikacji.

Wdrażanie wzrastającego czasu do ponowienia

W dokumentacji Google Cloud Storage znajdziesz informacje o wzrastającym czasie do ponowienia i o tym, jak go używać w interfejsach API Google.

Błędy i sugerowane działania

W tej sekcji znajdziesz pełną reprezentację JSON każdego wymienionego błędu oraz sugerowane działania, które możesz podjąć, aby sobie z nim poradzić.

400: Nieprawidłowe żądanie

Błąd użytkownika. Ten błąd występuje, gdy nie podasz wymaganego pola lub parametru, podasz nieprawidłową wartość albo podasz nieprawidłową kombinację pól.

{
  "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."
  }
}

Sugerowane działanie: ponieważ jest to błąd trwały, nie próbuj ponownie. Zamiast tego przeczytaj komunikat o błędzie i odpowiednio zmień żądanie.

401: Nieprawidłowe dane logowania

Nieprawidłowy nagłówek autoryzacji. Używany token dostępu wygasł lub jest nieprawidłowy.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization"
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

Sugerowane działania

403: Przekroczono limit na użytkownika

Osiągnięto jeden z limitów w konsoli Google Cloud.

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

Sugerowane działania

403: Przekroczono limit częstotliwości

Użytkownik osiągnął maksymalną częstotliwość wniosków interfejsu Calendar API na kalendarz lub na uwierzytelnionego użytkownika.

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

Sugerowane działanie: rateLimitExceeded błędy mogą zwracać kody błędów 403 lub 429 – są one funkcjonalnie podobne i należy je obsługiwać w ten sam sposób, używając wzrastającego czasu do ponowienia. Dodatkowo upewnij się, że Twoja aplikacja jest zgodna ze sprawdzonymi metodami opisanymi w artykule Zarządzanie limitami przydziału.

403: Przekroczono limity korzystania z Kalendarza

Użytkownik osiągnął jeden z limitów Kalendarza, które mają chronić użytkowników i infrastrukturę Google przed nadużyciami.

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "message": "Calendar usage limits exceeded.",
        "reason": "quotaExceeded"
      }
    ],
    "code": 403,
    "message": "Calendar usage limits exceeded."
  }
}

Sugerowane działania

403: Dostęp zabroniony dla osób innych niż organizator

Żądanie aktualizacji wydarzenia próbuje ustawić jedną z udostępnionych właściwości wydarzenia w kopii, która nie należy do organizatora. Tylko organizator może ustawiać udostępnione właściwości (np. guestsCanInviteOthers, guestsCanModify lub guestsCanSeeOtherGuests).

{
  "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."
  }
}

Sugerowane działania

  • Jeśli używasz metod Events: insert, Events: import lub Events: update, a Twoje żądanie nie zawiera żadnych udostępnionych właściwości, jest to równoznaczne z próbą ustawienia ich wartości domyślnych. Rozważ użycie metody Events: patch zamiast tego.
  • Jeśli Twoje żądanie zawiera udostępnione właściwości, upewnij się, że próbujesz zmienić te właściwości tylko wtedy, gdy aktualizujesz kopię organizatora.

404: Nie znaleziono

Nie udało się znaleźć podanego zasobu. Może się to zdarzyć w kilku przypadkach. Oto kilka przykładów:

  • Gdy żądany zasób (o podanym identyfikatorze) nigdy nie istniał.
  • Gdy użytkownik próbuje uzyskać dostęp do kalendarza, do którego nie ma dostępu.
{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "Not Found"
      }
    ],
    "code": 404,
    "message": "Not Found"
  }
}

Sugerowane działanie: Użyj wzrastającego czasu do ponowienia.

409: Żądany identyfikator już istnieje

W magazynie już istnieje instancja o podanym identyfikatorze.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "duplicate",
        "message": "The requested identifier already exists."
      }
    ],
    "code": 409,
    "message": "The requested identifier already exists."
  }
}

Sugerowane działanie: Jeśli chcesz utworzyć nową instancję, wygeneruj nowy identyfikator. W przeciwnym razie użyj metody events.update.

409: Konflikt

Nie można wykonać elementu w pakiecie w ramach operacji events.batch ze względu na konflikt operacyjny z innymi żądanymi elementami w pakiecie.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "conflict",
        "message": "Conflict"
      }
    ],
    "code": 409,
    "message": "Conflict"
  }
}

Sugerowane działanie: usuń ukończone i nieudane elementy, a następnie spróbuj ponownie wykonać pozostałe elementy w innym pakiecie events.batch lub w odpowiednich operacjach dotyczących pojedynczych wydarzeń.

410: Już nie istnieje

Parametry syncToken lub updatedMin są już nieprawidłowe. Ten błąd może też wystąpić, jeśli żądanie próbuje usunąć wydarzenie, które zostało już usunięte.

{
  "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."
  }
}

lub

{
  "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."
  }
}

lub

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "deleted",
        "message": "Resource has been deleted"
      }
    ],
    "code": 410,
    "message": "Resource has been deleted"
  }
}

Sugerowane działanie: w przypadku parametrów syncToken lub updatedMin wyczyść magazyn i ponownie zsynchronizuj dane. Więcej informacji znajdziesz w artykule Efektywne synchronizowanie zasobów. W przypadku wydarzeń, które zostały już usunięte, nie trzeba podejmować żadnych działań.

412: Nie spełniono warunku wstępnego

ETag podany w nagłówku If-Match nie odpowiada już bieżącemu ETagowi zasobu.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "conditionNotMet",
        "message": "Precondition Failed",
        "locationType": "header",
        "location": "If-Match"
      }
    ],
    "code": 412,
    "message": "Precondition Failed"
  }
}

Sugerowane działanie: pobierz ponownie encję i zastosuj zmiany. Więcej informacji znajdziesz w artykule Pobieranie określonych wersji zasobów.

429: Zbyt wiele żądań

Błąd rateLimitExceeded występuje, gdy użytkownik wysłał zbyt wiele żądań w danym czasie.

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

Sugerowane działanie: rateLimitExceeded błędy mogą zwracać kody błędów 403 lub 429 – są one funkcjonalnie podobne i należy je obsługiwać w ten sam sposób, używając wzrastającego czasu do ponowienia. Dodatkowo upewnij się, że Twoja aplikacja jest zgodna ze sprawdzonymi metodami opisanymi w artykule Zarządzanie limitami przydziału.

500: Błąd backendu

Podczas przetwarzania żądania wystąpił nieoczekiwany błąd.

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

Sugerowane działanie: Użyj wzrastającego czasu do ponowienia.