Obsługa błędów interfejsu API

Interfejs Calendar 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 szczegółami, które mogą pomóc w określeniu sposobu obsługi błędu.

W pozostałej części tej strony znajdziesz listę błędów Kalendarza wraz z wskazówkami dotyczącymi ich obsługi w aplikacji.

Wdrażanie wzrastającego czasu do ponowienia

W dokumentacji interfejsów API Cloud znajdziesz dobre wyjaśnienie, czym jest wycofywanie wykładnicze i jak go używać w przypadku interfejsów API Google.

Błędy i sugerowane działania

Ta sekcja zawiera pełną reprezentację JSON każdego wymienionego błędu oraz sugerowane działania, które możesz podjąć, aby go rozwiązać.

400. Nieprawidłowe żądanie

Błąd użytkownika. Może to oznaczać, że nie podano wymaganego pola lub parametru, podana wartość jest nieprawidłowa lub kombinacja podanych pól jest nieprawidłowa.

{
 "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ń prośbę.

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 użytkownika

Osiągnięto jeden z limitów w Konsoli programisty.

{
 "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ą liczbę żądań interfejsu Google 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: błędy rateLimitExceeded mogą zwracać kody błędów 403 lub 429 – obecnie są one funkcjonalnie podobne i należy na nie odpowiadać w ten sam sposób, czyli przy użyciu wykładniczego wycofywania. Upewnij się też, że Twoja aplikacja jest zgodna ze sprawdzonymi metodami z artykułu zarządzanie limitami.

403. Przekroczono limity korzystania z Kalendarza

Użytkownik osiągnął jeden z limitów Kalendarza Google, 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, które nie są organizatorami

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

{
 "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 Events: insert, Events: import lub Events: update, a Twoje żądanie nie zawiera żadnych właściwości wspólnych, jest to równoznaczne z próbą ustawienia ich wartości domyślnych. Zamiast tego możesz użyć metody Events: patch.
  • Jeśli Twoje żądanie ma właściwości udostępnione, upewnij się, że próbujesz zmienić te właściwości tylko wtedy, gdy aktualizujesz kopię organizatora.

404. Nie znaleziono

Nie znaleziono podanego zasobu. Może się to zdarzyć w kilku przypadkach. Oto przykłady:

  • gdy żądany zasób (o podanym identyfikatorze) nigdy nie istniał;

  • podczas uzyskiwania dostępu do kalendarza, do którego użytkownik 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

Instancja o podanym identyfikatorze już istnieje w pamięci.

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

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

409. Konflikt

Element w operacji events.batch nie może zostać wykonany z powodu konfliktu operacyjnego z innymi żądanymi elementami w operacji.

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

Sugerowane działanie: wyklucz wszystkie pakiety, które zostały ukończone, i wszystkie, które na pewno zakończyły się niepowodzeniem, a pozostałe spróbuj ponownie w ramach innych operacji events.batch lub odpowiednich operacji na pojedynczych zdarzeniach.

410. Już nie istnieje

Parametry syncToken lub updatedMin są już nieważne. Ten błąd może też wystąpić, gdy w ramach żądania podjęto próbę usunięcia wydarzenia, 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ść pamięć i ponownie zsynchronizuj dane. Więcej informacji znajdziesz w artykule Synchronizowanie zasobów w efektywny sposób. W przypadku usuniętych już wydarzeń nie musisz podejmować żadnych dodatkowych działań.

412. Nie spełniono warunku wstępnego

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

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

Sugerowane działanie: ponownie pobierz element i zastosuj zmiany. Więcej informacji znajdziesz w artykule Pobieranie konkretnych wersji zasobów.

429. Zbyt wiele żądań

Błąd rateLimitExceeded występuje, gdy użytkownik wyśle zbyt wiele żądań w określonym czasie.

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

Sugerowane działanie: błędy rateLimitExceeded mogą zwracać kody błędów 403 lub 429 – obecnie są one funkcjonalnie podobne i należy na nie odpowiadać w ten sam sposób, czyli przy użyciu wykładniczego wycofywania. Upewnij się też, że Twoja aplikacja jest zgodna ze sprawdzonymi metodami z artykułu zarządzanie limitami.

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.