Naprawianie błędów

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

  • kodów błędów HTTP i komunikatów nagłówków.
  • Obiekt JSON w treści odpowiedzi z dodatkowymi informacjami, które pomagają określić sposób postępowania z błędem.

Aplikacje Dysku Google powinny wychwytywać i obsługiwać wszystkie błędy, które mogą wystąpić podczas korzystania z interfejsu API REST. W tym przewodniku znajdziesz instrukcje rozwiązywania konkretnych błędów interfejsu Drive API.

Podsumowanie kodu stanu HTTP

Kod błędu Opis
200 - OK Żądanie powiodło się (jest to standardowa odpowiedź w przypadku udanych żądań HTTP).
400 - Bad Request Nie można zrealizować żądania z powodu błędu klienta w żądaniu.
401 - Unauthorized Żądanie zawiera nieprawidłowe dane logowania.
403 - Forbidden Żądanie zostało odebrane i zrozumiane, ale użytkownik nie ma uprawnień, by je zrealizować.
404 - Not Found Nie udało się znaleźć żądanej strony.
429 - Too Many Requests Zbyt wiele żądań do interfejsu API.
500, 502, 503, 504 - Server Errors Podczas przetwarzania żądania wystąpił nieoczekiwany błąd.

Błędy 400

Błędy te oznaczają, że żądanie było niedopuszczalne, często z powodu braku wymaganego parametru.

badRequest

Ten błąd może wystąpić z jednego z tych problemów w kodzie:

  • Nie podano wymaganego pola lub parametru.
  • Podana wartość lub kombinacja podanych pól jest nieprawidłowa.
  • Próbujesz dodać zduplikowany element nadrzędny do pliku na Dysku.
  • Próbujesz dodać element nadrzędny, który spowodowałby utworzenie cyklu na wykresie katalogu.

Poniższy przykładowy kod JSON przedstawia błąd:

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

Aby naprawić ten błąd, sprawdź pole message i odpowiednio dostosuj kod.

invalidSharingRequest

Ten błąd występuje z kilku powodów. Aby ustalić przyczynę, oceń pole reason zwróconego pliku JSON. Ten błąd występuje najczęściej, ponieważ:

  • Udało się udostępnić, ale e-mail z powiadomieniem nie został poprawnie dostarczony.
  • Zmiana listy kontroli dostępu (ACL) jest niedozwolona w przypadku tego użytkownika.

Pole message wskazuje rzeczywisty błąd.

Udostępnianie udało się, ale e-mail z powiadomieniem nie został poprawnie dostarczony

Poniższy przykładowy kod JSON przedstawia błąd:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "invalidSharingRequest",
        "message": "Bad Request. User message: \"Sorry, the items were successfully shared but emails could not be sent to email@domain.com.\""
      }
    ],
    "code": 400,
    "message": "Bad Request"
  }
}

Aby naprawić ten błąd, poinformuj użytkownika (udostępniającego), że nie udało się udostępnić pliku, ponieważ nie udało się wysłać e-maila z powiadomieniem na docelowy adres e-mail. Użytkownik powinien sprawdzić, czy ma prawidłowy adres e-mail i czy może odbierać e-maile.

Ten użytkownik nie może zmienić listy kontroli dostępu

Poniższy przykładowy kod JSON przedstawia błąd:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "invalidSharingRequest",
        "message": "Bad Request. User message: \"ACL change not allowed.\""
      }
    ],
    "code": 400,
    "message": "Bad Request"
  }
}

Aby naprawić ten błąd, sprawdź ustawienia udostępniania domeny Google Workspace, do której należy plik. Ustawienia mogą uniemożliwiać udostępnianie poza domenę lub udostępnianie dysku współdzielonego.

Błędy 401

Te błędy oznaczają, że żądanie nie zawiera prawidłowego tokena dostępu.

authError

Ten błąd występuje, gdy używany przez Ciebie token dostępu stracił ważność lub jest nieprawidłowy. Ten błąd może też być spowodowany brakiem autoryzacji dla żądanych zakresów. Poniższy przykładowy kod JSON przedstawia błąd:

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

Aby naprawić ten błąd, odśwież token dostępu za pomocą długoterminowego tokena odświeżania. Jeśli to się nie uda, przekieruj użytkownika przez proces OAuth zgodnie z opisem w sekcji Wybieranie zakresów interfejsu API Dysku Google.

Błędy 403

Te błędy oznaczają, że limit wykorzystania został przekroczony lub użytkownik nie ma odpowiednich uprawnień. Aby określić przyczynę, oceń pole reason zwróconego pliku JSON.

Informacje o limitach interfejsu Drive API znajdziesz w artykule Limity wykorzystania. Informacje o limitach folderów na Dysku znajdziesz w artykule Limity plików i folderów.

activeItemCreationLimitExceeded

Błąd activeItemCreationLimitExceeded występuje, gdy przekroczono limit liczby produktów utworzonych na konto. Każdy użytkownik może mieć do 500 milionów elementów utworzonych na jednym koncie. Więcej informacji znajdziesz w artykule Limit produktów użytkownika.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "activeItemCreationLimitExceeded",
    "message": "This account has exceeded the creation limit of 500 million items. To create more items, permanently delete some items."
   }
  ],
  "code": 403,
  "message": "This account has exceeded the creation limit of 500 million items. To create more items, permanently delete some items."
 }
}

Aby naprawić ten błąd:

  1. Poinformuj użytkownika, że Dysk uniemożliwia kontom tworzenie ponad 500 milionów elementów.

  2. Jeśli użytkownik musi utworzyć elementy na tym samym koncie, poproś go o trwałe usunięcie niektórych obiektów. W przeciwnym razie może użyć innego konta, które spełnia już te wymagania.

appNotAuthorizedToFile

Ten błąd występuje, gdy aplikacji nie ma na liście kontroli dostępu pliku dla tego pliku. Ten błąd uniemożliwia użytkownikowi otwarcie pliku w Twojej aplikacji. Przedstawił on ten przykład w formacie JSON:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "appNotAuthorizedToFile",
        "message": "The user has not granted the app {appId} {verb} access to the file {fileId}."
      }
    ],
    "code": 403,
    "message": "The user has not granted the app {appId} {verb} access to the file {fileId}."
  }
}

Aby naprawić ten błąd, wykonaj jedną z tych czynności:

  • Otwórz selektor Dysku Google i poproś użytkownika o otwarcie pliku.
  • Poinstruuj użytkownika, aby otworzył plik za pomocą menu kontekstowego Otwórz za pomocą w interfejsie Dysku aplikacji.
  • Za pomocą metody files.get sprawdź pole isAppAuthorized w zasobie files, aby sprawdzić, czy aplikacja utworzyła lub otworzyła plik.

cannotModifyInheritedTeamDrivePermission

Ten błąd występuje, gdy użytkownik próbuje zmienić odziedziczone uprawnienia do elementu na dysku współdzielonym. Odziedziczonych uprawnień nie można usunąć z elementu na dysku współdzielonym. Poniższy przykładowy kod JSON przedstawia błąd:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "cannotModifyInheritedTeamDrivePermission",
        "message": "Cannot update or delete an inherited permission on a shared drive item."
      }
    ],
    "code": 403,
    "message": "Cannot update or delete an inherited permission on a shared drive item."
  }
}

Aby naprawić ten błąd, użytkownik musi dostosować uprawnienia bezpośredniego lub pośredniego elementu nadrzędnego, z którego został odziedziczony. Więcej informacji znajdziesz w artykule na temat propagacji uprawnień. Możesz też pobrać zasób permissions.permissionDetails, aby sprawdzić, czy uprawnienia do tego elementu na dysku współdzielonym są dziedziczone czy stosowane bezpośrednio.

dailyLimitExceeded

Ten błąd występuje po osiągnięciu limitu interfejsów API w projekcie. Ten błąd ilustruje ten przykład JSON:

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

Ten błąd pojawia się, gdy właściciel aplikacji ustawił limit ograniczający wykorzystanie konkretnego zasobu. Aby naprawić ten błąd, usuń wszelkie limity wykorzystania dotyczące limitu „zapytań dziennie”.

domainPolicy

Ten błąd występuje, gdy zasady domeny użytkownika nie zezwalają Twojej aplikacji na dostęp do Dysku. Przykład tego błędu w formacie JSON przedstawia ten błąd:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Drive apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Drive apps."
  }
}

Aby naprawić ten błąd:

  1. Poinformuj użytkownika, że domena nie zezwala aplikacji na dostęp do plików na Dysku.
  2. Poproś użytkownika, aby skontaktował się z administratorem domeny i poprosił go o dostęp do Twojej aplikacji.

fileOwnerNotMemberOfTeamDrive

Ten błąd występuje, gdy właściciel pliku nie jest użytkownikiem dysku współdzielonego, gdy próbujesz przenieść go na dysk współdzielony. Poniższy przykładowy kod JSON przedstawia błąd:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "fileOwnerNotMemberOfTeamDrive",
        "message": "Cannot move a file into a shared drive as a writer when the owner of the file is not a member of that shared drive."
      }
    ],
    "code": 403,
    "message": "Cannot move a file into a shared drive as a writer when the owner of the file is not a member of that shared drive."
  }
}

Aby naprawić ten błąd:

  1. Dodaj użytkownika do dysku współdzielonego jako role=owner. Więcej informacji znajdziesz w artykule Udostępnianie plików, folderów i dysków.

  2. Dodaj plik do dysku współdzielonego. Więcej informacji znajdziesz w artykule Tworzenie i wypełnianie folderów.

fileWriterTeamDriveMoveInDisabled

Ten błąd występuje, gdy administrator domeny nie zezwolił użytkownikom w domenie role=writer na przenoszenie elementów na dysk współdzielony. Użytkownik, który próbuje przenieść elementy, ma mniej uprawnień niż dozwolone na docelowym dysku współdzielonym. Poniższy przykładowy kod JSON przedstawia ten błąd:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "fileWriterTeamDriveMoveInDisabled",
        "message": "The domain administrator has not allowed writers to move items into a shared drive."
      }
    ],
    "code": 403,
    "message": "The domain administrator has not allowed writers to move items into a shared drive."
  }
}

Aby naprawić ten błąd, użyj tego samego konta administratora zarówno na źródłowym, jak i na docelowym dysku współdzielonym.

insufficientFilePermissions

Ten błąd występuje, gdy użytkownik nie ma uprawnień do zapisu pliku, a aplikacja próbuje go zmodyfikować. Poniższy przykładowy kod JSON przedstawia błąd:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "insufficientFilePermissions",
        "message": "The user does not have sufficient permissions for file {fileId}."
      }
    ],
    "code": 403,
    "message": "The user does not have sufficient permissions for file {fileId}."
  }
}

Aby naprawić ten błąd, poproś użytkownika, aby skontaktował się z właścicielem pliku i poprosił o uprawnienia do edycji. Możesz też sprawdzić poziomy dostępu użytkowników w metadanych pobranych przez metodę files.get i wyświetlić interfejs tylko do odczytu w przypadku braku uprawnień.

myDriveHierarchyDepthLimitExceeded

Błąd myDriveHierarchyDepthLimitExceeded występuje, gdy przekroczono limit liczby zagnieżdżonych poziomów folderów. Mój dysk użytkownika może zawierać maksymalnie 100 poziomów zagnieżdżonych folderów. Więcej informacji znajdziesz w sekcji Limit głębokości folderów.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "myDriveHierarchyDepthLimitExceeded",
    "message": "Your My Drive can't contain more than 100 levels of folders. For details, see https://developers.google.com/drive/api/guides/handle-errors#nested-folder-levels."
   }
  ],
  "code": 403,
  "message": "Your My Drive can't contain more than 100 levels of folders. For details, see https://developers.google.com/drive/api/guides/handle-errors#nested-folder-levels."
 }
}

Aby naprawić ten błąd:

  1. Poinformuj użytkownika, że Dysk nie zezwala na umieszczanie folderów na ponad 100 poziomach.
  2. Jeśli użytkownik musi utworzyć kolejny zagnieżdżony folder, poinstruuj go, aby uporządkował docelowy folder nadrzędny tak, aby miał mniej niż 100 poziomów lub użyć innego folderu nadrzędnego, który już spełnia to wymaganie.

numChildrenInNonRootLimitExceeded

Ten błąd występuje, gdy przekroczono limit liczby elementów podrzędnych folderu (folderów, plików i skrótów). Obowiązuje limit 500 000 elementów dla folderów, plików i skrótów bezpośrednio w folderze. Elementy zagnieżdżone w podfolderach nie wliczają się do limitu 500 tys. elementów. Więcej informacji o limitach folderów na Dysku znajdziesz w artykule Limity dotyczące folderów na Dysku Google.

Poniższy przykładowy kod JSON przedstawia błąd:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "numChildrenInNonRootLimitExceeded",
    "message": "The limit for this folder's number of children (files and folders) has been exceeded."
   }
  ],
  "code": 403,
  "message": "The limit for this folder's number of children (files and folders) has been exceeded."
 }
}

Aby naprawić ten błąd, wykonaj jedną z tych czynności:

  • Poinformuj użytkownika,że Dysk blokuje foldery zawierające ponad 500 tys. elementów.
  • Jeśli użytkownik musi dodać więcej elementów do pełnego folderu, poinstruuj go, aby zmienił organizację folderu tak, aby zawierał mniej niż 500 000 elementów, lub użycie podobnego folderu, który już zawiera mniej elementów.

rateLimitExceeded

Ten błąd występuje po osiągnięciu limitu liczby żądań w projekcie. Ten limit różni się w zależności od typu żądania. Poniższy przykładowy kod JSON przedstawia błąd:

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

Aby naprawić ten błąd, wykonaj jedną z tych czynności:

sharingRateLimitExceeded

Ten błąd występuje, gdy użytkownik osiągnie limit udostępniania i często jest związany z limitem adresów e-mail. Poniższy przykładowy kod JSON przedstawia błąd:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "message": "Rate limit exceeded. User message: \"These item(s) could not be shared because a rate limit was exceeded: filename",
    "reason": "sharingRateLimitExceeded",
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

Aby naprawić ten błąd:

  1. Nie wysyłaj e-maili, gdy udostępniasz dużą liczbę plików.
  2. Jeśli jeden użytkownik wysyła wiele żądań w imieniu wielu użytkowników konta Google Workspace, rozważ utworzenie konta usługi z przekazanym dostępem w całej domenie za pomocą parametru quotaUser.

storageQuotaExceeded

Ten błąd występuje, gdy użytkownik osiągnie limit miejsca na dane. Ten błąd ilustruje ten przykład JSON:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "message": "The user's Drive storage quota has been exceeded.",
    "reason": "storageQuotaExceeded",
   }
  ],
  "code": 403,
  "message": "The user's Drive storage quota has been exceeded."
 }
}

Aby naprawić ten błąd:

  1. Sprawdź swoje limity miejsca na Dysku. Więcej informacji znajdziesz w artykule Limity miejsca na dane i przesyłania w Google Workspace.

  2. zarządzać plikami na Dysku Google;

  3. Kupowanie dodatkowego miejsca na dane w Google.

teamDriveFileLimitExceeded

Ten błąd występuje, gdy użytkownik próbuje przekroczyć rygorystyczny limit elementów na dysku współdzielonym. Każdy folder na dysku współdzielonym użytkownika może zawierać maksymalnie 400 tys. elementów, w tym plików, folderów i skrótów. Ten limit bazuje na liczbie elementów, a nie na wykorzystaniu miejsca na dane. Więcej informacji znajdziesz w artykule Limity dysków współdzielonych na Dysku Google.

Poniższy przykładowy kod JSON przedstawia błąd:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDriveFileLimitExceeded",
        "message": "The file limit for this shared drive has been exceeded."
      }
    ],
    "code": 403,
    "message": "The file limit for this shared drive has been exceeded."
  }
}

Aby naprawić ten błąd, zmniejsz liczbę elementów na dysku współdzielonym. Dyski współdzielone ze zbyt dużą liczbą plików mogą być trudne do porządkowania i wyszukiwania.

teamDriveMembershipRequired

Ten błąd występuje, gdy użytkownik próbuje uzyskać dostęp do dysku współdzielonego, do którego nie jest użytkownikiem. Poniższy przykładowy kod JSON przedstawia błąd:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDriveMembershipRequired",
        "message": "The attempted action requires shared drive membership."
      }
    ],
    "code": 403,
    "message": "The attempted action requires shared drive membership."
  }
}

Aby naprawić ten błąd, wykonaj jedną z tych czynności:

  1. Poproś menedżera dysku współdzielonego, aby dodał Cię z odpowiednimi uprawnieniami do wykonanej czynności.

  2. Przejrzyj Role i uprawnienia Dysku, aby dowiedzieć się, kto ma dostęp do dysków współdzielonych i może nimi zarządzać. Dodatkowe informacje o poziomach dostępu znajdziesz też w artykule Tworzenie dysku współdzielonego.

teamDrivesFolderMoveInNotSupported

Ten błąd występuje, gdy użytkownik próbuje przenieść folder z Mojego dysku na dysk współdzielony. Poniższy przykładowy kod JSON przedstawia błąd:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDrivesFolderMoveInNotSupported",
        "message": "Moving folders into shared drives is not supported."
      }
    ],
    "code": 403,
    "message": "Moving folders into shared drives is not supported."
  }
}

Aby naprawić ten błąd, wykonaj jedną z tych czynności:

  • Przenieś poszczególne elementy z folderu na dysk współdzielony za pomocą interfejsu Drive API. Ustaw parametr supportsAllDrives=true, aby wskazać, że obsługuje zarówno Mój dysk, jak i dyski współdzielone.

  • Jeśli musisz przenieść folder na dysk współdzielony, użyj interfejsu Dysku. Więcej informacji znajdziesz w artykule o przenoszeniu folderów na dyski współdzielone przez administratora.

teamDrivesParentLimit

Ten błąd występuje, gdy użytkownik próbuje dodać więcej niż 1 element nadrzędny do elementu na dysku współdzielonym. Poniższy przykładowy kod JSON przedstawia błąd:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDrivesParentLimit",
        "message": "A shared drive item must have exactly one parent."
      }
    ],
    "code": 403,
    "message": "A shared drive item must have exactly one parent."
  }
}

Aby naprawić ten błąd, dodaj wiele linków do pliku za pomocą skrótów Dysku. Skrót może mieć tylko 1 element nadrzędny, ale plik skrótu można skopiować do dodatkowych lokalizacji. Więcej informacji znajdziesz w artykule Tworzenie skrótu do pliku na Dysku.

UrlLeaseLimitExceeded

Ten błąd występuje, gdy próbujesz zapisać dane gier z Google Play za pomocą aplikacji. Poniższy przykładowy kod JSON przedstawia błąd:

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "UrlLeaseLimitExceeded",
    "message": "Too many pending uploads for this snapshot. Please finish or cancel some before creating more."
   }
  ],
  "code": 403,
  "message": "Too many pending uploads for this snapshot. Please finish or cancel some before creating more."
 }
}

Aby naprawić ten błąd, dokończ lub anuluj przesyłanie zrzutu, zanim utworzysz kolejne.

userRateLimitExceeded

Ten błąd występuje po osiągnięciu limitu na użytkownika. Może to być limit wynikający z konsoli Google Cloud lub z backendu Dysku. Poniższy przykładowy kod JSON przedstawia błąd:

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

Aby naprawić ten błąd, wykonaj jedną z tych czynności:

Informacje o limitach interfejsu Drive API znajdziesz w artykule Limity wykorzystania.

Błędy 404

Te błędy oznaczają, że żądany zasób jest niedostępny lub nie istnieje.

notFound

Ten błąd występuje, gdy użytkownik nie ma uprawnień do odczytu pliku lub plik nie istnieje. Poniższy przykładowy kod JSON przedstawia błąd:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "File not found {fileId}"
      }
    ],
    "code": 404,
    "message": "File not found: {fileId}"
  }
}

Aby naprawić ten błąd:

  1. Poinformuj użytkownika, że nie ma uprawnień do odczytu pliku lub plik nie istnieje.
  2. Poproś użytkownika, aby skontaktował się z właścicielem pliku i poprosił go o pozwolenie.

Błędy 429

Te błędy oznaczają, że do interfejsu API wysłano zbyt wiele żądań.

rateLimitExceeded

Ten błąd występuje, gdy użytkownik wysłał zbyt wiele żądań w danym okresie. Poniższy przykładowy kod JSON przedstawia błąd:

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

Aby naprawić ten błąd, użyj funkcji wykładniczego ponowienia, aby ponowić żądanie.

Błędy 500, 502, 503, 504

Błędy te występują, gdy podczas przetwarzania żądania wystąpi nieoczekiwany błąd serwera. Błędy te mogą być spowodowane różnymi problemami, takimi jak czas oczekiwania żądania na inne żądanie lub żądanie nieobsługiwanego działania – np. próba zaktualizowania uprawnień do pojedynczej strony w Witrynach Google zamiast do całej witryny.

Poniżej znajduje się lista błędów 5xx:

  • Błąd 500 backendu
  • 502 Nieprawidłowa brama
  • 503 Usługa niedostępna
  • Przekroczenie limitu czasu bramy 504

Aby naprawić ten błąd, użyj funkcji wykładniczego ponowienia, aby ponowić żądanie.