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 wykrywać i obsługiwać wszystkie błędy, które napotkasz podczas korzystania z interfejsu REST API. Ten przewodnik zawiera instrukcje rozwiązywania konkretnych błędów interfejsu Gmail API.

Podsumowanie kodów stanu HTTP

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:

• Brak wymaganego pola lub parametru.
• Podana wartość lub kombinacja 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 żądanych zakresów. 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 OAuth, zgodnie z opisem 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 zwróconego kodu JSON. Ten błąd występuje w tych sytuacjach:

• Nie można używać aplikacji w domenie uwierzytelnionego użytkownika.
• Projekt przekroczył limit dzienny.
• Użytkownik przekroczył limit.
• Projekt przekroczył limit częstotliwości.

Więcej informacji znajdziesz w sekcji Limity wykorzystania.

dailyLimitExceeded

Ten błąd występuje, gdy projekt osiągnie limit interfejsu API. 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 występuje, gdy właściciel aplikacji ustawi limit, aby ograniczyć wykorzystanie określonego zasobu. Aby naprawić ten błąd, zwiększ limit w projekcie Google Cloud. Więcej informacji znajdziesz w artykule o zarządzaniu limitami.

domainPolicy

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

{
  "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:

1. Poinformuj użytkownika, że domena nie zezwala aplikacji na dostęp do Gmaila.
2. 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ą liczbę żądań w przypadku interfejsu Gmail API. Limit ten 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 żądanie osiągnie limit liczby żądań na użytkownika. Poniższy przykład 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.

Nie możesz zwiększyć limitów na użytkownika. 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 wersji próbnej Gmaila. 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 przekroczysz te limity, interfejs API zwróci 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 kilka godzin, zanim serwer zaakceptuje żądanie.

Proces wysyłania e-maili 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.

Użytkownicy zwykle napotykają te limity tylko w wyjątkowych lub nadużywających sytuacjach. Jeśli przekroczysz te limity, interfejs API zwróci błąd HTTP 429 „Za dużo żądań: przekroczono limit liczby żądań użytkownika” z czasem ponowienia. Przekroczenie dziennych limitów może powodować te błędy przez kilka godzin, zanim serwer zaakceptuje żądanie.

Równoczesne żądania

Interfejs Gmail API wymusza limit żądań równoczesnych na użytkownika (oprócz limitu częstotliwoś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 przekroczysz ten limit, interfejs API zwróci błąd HTTP 429 „Too many requests: Too many concurrent requests for user” (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. nakładanie się w czasie żądania z innym żądaniem lub żądanie nieobsługiwanego działania, np. próba zaktualizowania uprawnień do pojedynczej strony w Usługach Google zamiast do całej witryny.

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

• 500 Błąd backendu
• 502 Nieprawidłowa brama
• 503 Usługa niedostępna
• 504 Przekroczono limit 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 ponownie wysłać żądanie.

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. Możesz na przykład 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 zwiększania wykorzystania przepustowości oraz maksymalizowania przepustowości żądań w środowiskach współbieżnych.

Okresy ponawiania 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:

1. Jeśli nie masz jeszcze konta rozliczeniowego dla projektu, utwórz je.
2. Otwórz stronę Włączone interfejsy API w  bibliotece interfejsów API w Konsoli interfejsów API i wybierz interfejs API z listy.
3. 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

Żądania wsadowe mogą zwiększyć wydajność, ale większe rozmiary wsadu mogą spowodować ograniczenie liczby żądań. Nie wysyłaj partii większych niż 50 żądań. Informacje o tym, jak wysyłać żądania zbiorcze, znajdziesz w artykule Żądania zbiorcze.

Powiązane artykuły

• Wskazówki dotyczące wydajności
• Rozwiązywanie problemów z uwierzytelnianiem i autoryzacją