Naprawianie błędów

Interfejs Gmail 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.

Aplikacja Gmail powinna przechwytywać i obsługiwać wszystkie błędy, które mogą wystąpić podczas korzystania z interfejsu REST API. Ten przewodnik zawiera instrukcje rozwiązywania konkretnych błędów interfejsu Gmail API.

Podsumowanie kodów stanu HTTP

Kod błędu	Opis
`200 - OK`	Żądanie zostało zrealizowane (jest to standardowa odpowiedź na udane żądania HTTP).
`400 - Bad Request`	Nie możemy zrealizować prośby 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ń do jego wykonania.
`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

Te błędy oznaczają, że żądanie zawiera błąd, często spowodowany brakiem wymaganego parametru.

`badRequest`

Ten błąd może wystąpić z jednej z tych przyczyn w kodzie:

Nie podano wymaganego pola ani parametru.
Podana wartość lub kombinacja podanych pól jest nieprawidłowa.
Załącznik jest nieprawidłowy.

Poniższy przykład JSON przedstawia ten 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.

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 token dostępu wygasł lub jest nieprawidłowy. Ten błąd może być też spowodowany brakiem autoryzacji w przypadku zakresów, o które prosisz. Poniższy przykład JSON przedstawia ten 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ługotrwałego tokena odświeżania. Jeśli używasz biblioteki klienta, automatycznie obsługuje ona odświeżanie tokena. Jeśli to się nie uda, przeprowadź użytkownika przez proces protokołu OAuth opisany w artykule Więcej informacji o uwierzytelnianiu i autoryzacji.

Więcej informacji o limitach Gmaila znajdziesz w artykule Limity użytkowania.

Błędy 403

Te błędy występują, gdy przekroczysz limit wykorzystania lub użytkownik nie ma odpowiednich uprawnień. Aby określić przyczynę, sprawdź pole reason w zwróconym pliku JSON. Ten błąd występuje w tych sytuacjach:

Nie można używać aplikacji w domenie uwierzytelnionego użytkownika.
Przekroczono limit dzienny.
Przekroczono limit użytkownika.
Przekroczono limit projektu.

Więcej informacji znajdziesz w sekcji Limity wykorzystania.

`dailyLimitExceeded`

Ten błąd występuje, gdy osiągnięty zostanie limit interfejsu API w Twoim projekcie. Poniższy przykład JSON przedstawia ten błąd:

{
  "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 wykorzystania określonego zasobu. Aby naprawić ten błąd, zwiększ limit w projekcie Google Cloud. Więcej informacji znajdziesz w artykule Zarządzanie limitami.

`domainPolicy`

Ten błąd występuje, gdy zasady domeny użytkownika nie zezwalają aplikacji na dostęp do Gmaila. Poniższy kod JSON przedstawia ten błąd:

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

Aby naprawić ten błąd:

Poinformuj użytkownika, że domena nie zezwala aplikacji na dostęp do Gmaila.
Poproś użytkownika, aby skontaktował się z administratorem domeny i poprosił o dostęp do Twojej aplikacji.

`rateLimitExceeded`

Ten błąd oznacza, że użytkownik osiągnął maksymalną częstotliwość wniosków w interfejsie Gmail API. Ten limit zależy od typu żądania. Poniższy przykład JSON przedstawia ten błąd:

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

Aby naprawić ten błąd:

Poproś o zwiększenie limitu.
Aby ponowić żądanie, użyj wzrastającego czasu do ponowienia.

`userRateLimitExceeded`

Ten błąd występuje, gdy osiągnięto limit liczby żądań na użytkownika. Ten przykładowy kod JSON przedstawia ten błąd:

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

Aby rozwiązać ten problem, spróbuj zoptymalizować kod aplikacji, aby wysyłać mniej żądań, lub użyj wzrastającego czasu do ponowienia, aby ponowić żądanie.

Błędy 429

Błąd 429 „Zbyt wiele żądań” może wystąpić z powodu dziennych limitów na użytkownika (w tym limitów wysyłania poczty), limitów przepustowości lub limitu jednoczesnych żądań na użytkownika. Poniżej znajdziesz informacje o poszczególnych limitach. Każdy limit można jednak rozwiązać, ponawiając nieudane żądania lub dzieląc przetwarzanie na wiele kont Gmail.

Limitów na użytkownika nie można zwiększyć z żadnego powodu. Więcej informacji o limitach znajdziesz w artykule Limity wykorzystania.

Limity wysyłania poczty

Interfejs Gmail API wymusza standardowe dzienne limity wysyłania e-maili. Te limity różnią się w przypadku płacących użytkowników Google Workspace i użytkowników kont gmail.com w okresie próbnym. Informacje o tych limitach znajdziesz w artykule Limity wysyłania Gmaila w Google Workspace.

Te limity dotyczą każdego użytkownika i są wspólne dla wszystkich jego klientów, niezależnie od tego, czy są to klienci API, wbudowani klienci internetowi czy SMTP MSA. Jeśli te limity zostaną przekroczone, zwracany jest błąd HTTP 429 „Za dużo żądań: przekroczono limit liczby żądań użytkownika (wysyłanie e-maili)” z czasem ponownej próby. Przekroczenie dziennych limitów może powodować te błędy przez wiele godzin, zanim żądanie zostanie zaakceptowane.

Proces wysyłania poczty jest złożony: gdy użytkownik przekroczy limit, może upłynąć kilka minut, zanim interfejs API zacznie zwracać odpowiedzi z błędem 429. Nie możesz zakładać, że odpowiedź 200 oznacza, że e-mail został wysłany.

Limity przepustowości

Interfejs API ma limity przepustowości przesyłania i pobierania danych dla poszczególnych użytkowników, które są równe limitom IMAP, ale od nich niezależne. Te limity są wspólne dla wszystkich klientów interfejsu Gmail API użytkownika.

Te limity są zwykle osiągane tylko w wyjątkowych lub nadużywanych sytuacjach. Jeśli te limity zostaną przekroczone, zwracany jest błąd HTTP 429 „Too many requests: User-rate limit exceeded” (Zbyt wiele żądań: przekroczono limit liczby żądań użytkownika) z czasem ponowienia próby. Przekroczenie dziennych limitów może powodować te błędy przez kilka godzin, zanim żądanie zostanie zaakceptowane.

Równoczesne żądania

Interfejs Gmail API wymusza limit żądań równoczesnych na użytkownika (oprócz limitu szybkości na użytkownika). Ten limit jest wspólny dla wszystkich klientów interfejsu Gmail API, którzy uzyskują dostęp do użytkownika. Zapewnia on, że żaden klient interfejsu API nie przeciąża skrzynki pocztowej użytkownika Gmaila ani jego serwera zaplecza.

Ten błąd może wystąpić, gdy wyślesz wiele równoległych żądań dotyczących jednego użytkownika lub wyślesz pakiety z dużą liczbą żądań. Ten błąd może też wystąpić, gdy duża liczba niezależnych klientów API jednocześnie uzyskuje dostęp do skrzynki pocztowej użytkownika Gmaila. Jeśli ten limit zostanie przekroczony, zwracany jest błąd HTTP 429 „Za dużo żądań: zbyt wiele jednoczesnych żądań użytkownika”.

Błędy 500, 502, 503 i 504

Te błędy występują, gdy podczas przetwarzania żądania wystąpi nieoczekiwany błąd serwera. Przyczyną tych błędów mogą być różne problemy, np. czas żądania pokrywający się z innym żądaniem lub żądanie nieobsługiwanego działania, np. próba zaktualizowania uprawnień do pojedynczej strony w Witrynach Google zamiast do całej witryny.

Poniżej znajdziesz listę błędów 5xx:

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

backendError

Ten błąd występuje, gdy podczas przetwarzania żądania wystąpi nieoczekiwany błąd. Poniższy przykład JSON przedstawia ten błąd:

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

Aby naprawić ten błąd, użyj wzrastającego czasu do ponowienia, aby ponowić próbę wysłania żądania.

Ponawianie nieudanych żądań w celu rozwiązania błędów

Możesz okresowo ponawiać nieudaną prośbę przez coraz dłuższy czas, aby obsługiwać błędy związane z limitami szybkości, natężeniem ruchu w sieci lub czasem odpowiedzi. Na przykład możesz ponowić nieudaną próbę po sekundzie, potem po dwóch sekundach, a następnie po czterech sekundach. Ta metoda nazywa się wzrastający czas do ponowienia i jest używana do poprawy wykorzystania przepustowości oraz maksymalizacji przepustowości żądań w środowiskach współbieżnych.

Okresy ponawiania prób powinny rozpoczynać się co najmniej sekundę po wystąpieniu błędu.

Zarządzaj limitami

Aby wyświetlić lub zmienić limity wykorzystania w projekcie albo poprosić o zwiększenie limitu:

Jeśli nie masz jeszcze konta rozliczeniowego dla projektu, utwórz je.
Otwórz stronę Włączone interfejsy API w bibliotece interfejsów API w Konsoli interfejsów API i wybierz interfejs API z listy.
Aby wyświetlić i zmienić ustawienia związane z limitami, kliknij Limity. Aby wyświetlić statystyki użytkowania, kliknij Użycie.

Więcej informacji znajdziesz w artykule o wyświetlaniu limitów i zarządzaniu nimi.

Żądania zbiorcze

Zalecamy korzystanie z żądań wsadowych, ale większe rozmiary wsadu mogą spowodować ograniczenie liczby żądań. Wysyłanie partii zawierających więcej niż 50 żądań nie jest zalecane. Informacje o wysyłaniu żądań zbiorczych znajdziesz w artykule Żądania zbiorcze.