Gmail API zwraca 2 poziomy informacji o błędach:
- kody i komunikaty błędów HTTP w nagłówku.
- Obiekt JSON w ciele odpowiedzi z dodatkowymi szczegółami, które mogą pomóc w określeniu sposobu postępowania z błędem.
Aplikacje Gmail powinny przechwytywać i obsługiwać wszystkie błędy, które mogą wystąpić podczas korzystania z interfejsu REST API. Z tego przewodnika dowiesz się, jak rozwiązać konkretne błędy interfejsu API.
Rozwiązywanie błędu 400: Nieprawidłowe żądanie
Ten błąd może być spowodowany tymi błędami w Twoim kodzie:
- Nie podano wymaganego pola lub parametru.
- Podana wartość lub kombinacja podanych pól jest nieprawidłowa.
- Nieprawidłowy załącznik.
Poniżej znajduje się przykładowy kod JSON tego błędu:
{
"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.
Rozwiązywanie błędu 401: nieprawidłowe dane uwierzytelniające
Błąd 401 oznacza, że token dostępu, którego używasz, wygasł lub jest nieprawidłowy. Ten błąd może być też spowodowany brakiem autoryzacji dla żądanych zakresów. Oto reprezentacja tego błędu w formacie JSON:
{
"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, będzie ona automatycznie odświeżać token. Jeśli to nie zadziała, poproś użytkownika o przejście procesu autoryzacji OAuth, jak opisano w artykule Autoryzowanie aplikacji za pomocą Gmaila.
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity wykorzystania.
Rozwiązywanie błędu 403: przekroczono limit użycia
Błąd 403 występuje, gdy przekroczono limit użycia lub użytkownik nie ma odpowiednich uprawnień. Aby określić konkretny typ błędu, sprawdź pole reason zwróconego pliku JSON. Ten błąd występuje w tych sytuacjach:
- Przekroczono dzienny limit.
- Przekroczono limit częstotliwości korzystania przez użytkownika.
- Przekroczono limit częstotliwości projektu.
- Aplikacji nie można używać w domenie uwierzytelnionego użytkownika.
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity wykorzystania.
Rozwiązywanie błędu 403: przekroczenie dziennego limitu
Błąd dailyLimitExceeded wskazuje, że osiągnięto limit interfejsu API dla bezpłatnego korzystania w projekcie. Oto reprezentacja tego błędu w formacie JSON:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "dailyLimitExceeded",
"message": "Daily Limit Exceeded"
}
],
"code": 403,
"message": "Daily Limit Exceeded"
}
}
Aby naprawić ten błąd:
- Otwórz konsolę interfejsów API Google.
- Wybierz projekt.
- Kliknij kartę Limity.
- Poproś o dodatkowy limit. Więcej informacji znajdziesz w artykule Prośba o dodatkowy limit.
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity wykorzystania.
Rozwiązywanie błędu 403: przekroczono limit częstotliwości dostępu użytkowników
Błąd userRateLimitExceeded wskazuje, że osiągnięto limit na użytkownika. Oto reprezentacja tego błędu w formacie JSON:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "userRateLimitExceeded",
"message": "User Rate Limit Exceeded"
}
],
"code": 403,
"message": "User Rate Limit Exceeded"
}
}
Aby naprawić ten błąd, zoptymalizuj kod aplikacji, aby wysyłać mniej żądań lub ponownie próbować wysyłać żądania. Informacje o ponownym wysyłaniu żądań znajdziesz w sekcji Ponawianie próśb o rozwiązanie problemów w przypadku niepowodzenia (materiały w języku angielskim).
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity wykorzystania.
Rozwiązywanie błędu 403: Przekroczono limit częstotliwości
Błąd rateLimitExceeded oznacza, że użytkownik osiągnął maksymalną częstotliwość żądań interfejsu Gmail API. Ten limit różni się w zależności od typu żądań.
Oto reprezentacja tego błędu w formacie JSON:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Rate Limit Exceeded",
"reason": "rateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Aby naprawić ten błąd, ponownie prześlij nieudane żądania.
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity wykorzystania.
Rozwiązywanie błędu 403: aplikacja o identyfikatorze {appId} nie może być używana w domenie uwierzytelnionego użytkownika
Błąd domainPolicy występuje, gdy zasady dotyczące domeny użytkownika nie zezwalają aplikacji na dostęp do Gmaila. Poniżej znajduje się reprezentacja tego błędu w formacie 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:
- Poinformuj użytkownika, że domena nie zezwala Twojej aplikacji na dostęp do Gmaila.
- Poproś użytkownika, aby skontaktował się z administratorem domeny i poprosił o dostęp do aplikacji.
Rozwiązywanie błędu 429: „Zbyt wiele żądań”
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 każdym z nich. Każdy limit można jednak rozwiązać, próbując ponownie wysłać nieudane żądania lub rozdzielając przetwarzanie na kilka 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 stosuje standardowe dzienne limity wysyłania poczty. Te limity różnią się w przypadku płatnych użytkowników Google Workspace i użytkowników gmail.com korzystających z wersji próbnej. Informacje o tych limitach znajdziesz w artykule Limity wysyłania Gmaila w Google Workspace.
Te limity są wspólne dla wszystkich klientów użytkownika, niezależnie od tego, czy są to klienci API, klienci natywnych aplikacji lub SMTP MSA. Jeśli te limity zostaną przekroczone, zwracany jest kod błędu HTTP 429 Too Many Requests „User-rate limit exceeded” („Mail sending”) z czasem ponownej próby.
Pamiętaj, że przekroczenie dziennych limitów może powodować występowanie tego typu błędów przez kilka godzin przed zaakceptowaniem prośby.
Proces wysyłania poczty jest złożony: gdy użytkownik przekroczy limit, może minąć kilka minut, zanim interfejs API zacznie zwracać odpowiedzi z błędem 429. Nie możesz więc zakładać, że odpowiedź 200 oznacza, że e-mail został wysłany.
Limity przepustowości
Interfejs API ma limity przepustowości na poszczególne konta użytkowników, które są takie same jak w IMAP, ale niezależne od niego. Te limity są wspólne dla wszystkich klientów interfejsu API Gmaila danego 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” (Przekroczony limit liczby żądań użytkownika) z czasem ponownej próby.
Pamiętaj, że przekroczenie dziennych limitów może powodować występowanie tego typu błędów przez kilka godzin, zanim prośba zostanie zaakceptowana.
Równoczesne żądania
Interfejs API Gmaila narzuca limit równoczesnych żądań na użytkownika (oprócz limitu częstotliwości na użytkownika). Ten limit jest wspólny dla wszystkich klientów interfejsu API Gmaila, którzy uzyskują dostęp do danego użytkownika, i zapewnia, że żaden klient interfejsu API nie przeciąża skrzynki pocztowej użytkownika Gmaila ani jego serwera zaplecza.
Może to spowodować wysyłanie wielu równoległych żądań dotyczących jednego użytkownika lub wysyłanie partii żądań zawierających dużą liczbę żądań. Ten błąd może też wywołać duża liczba niezależnych klientów interfejsu API, które jednocześnie uzyskują dostęp do skrzynki pocztowej użytkownika Gmaila. Jeśli ten limit zostanie przekroczony, zwrócony zostanie błąd HTTP 429 Too Many Requests„Too many concurrent requests for user” (Za dużo jednoczesnych żądań dla użytkownika).
Rozwiązywanie błędu 500: błąd backendu
Błąd backendError występuje, gdy podczas przetwarzania żądania wystąpi nieoczekiwany błąd.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
Aby naprawić ten błąd, ponownie prześlij nieudane żądania. Poniżej znajduje się lista błędów 500:
- 502 Nieprawidłowa brama
- 503 Usługa niedostępna
- 504 Przekroczenie limitu czasu bramy
Ponawianie nieudanych żądań w celu rozwiązania problemów
Aby obsługiwać błędy związane z ograniczeniami szybkości, natężeniem ruchu w sieci lub czasem odpowiedzi, możesz okresowo powtarzać nieudane próby wysłania żądania z coraz dłuższymi przerwami. Na przykład możesz ponownie wysłać nieudane żądanie po 1 sekundzie, potem po 2 sekundach, a następnie po 4 sekundach. Ta metoda nosi nazwę exponential backoff (zwrotna funkcja wykładnicza) i służy do zwiększenia wykorzystania przepustowości oraz maksymalizacji przepustowości żądań w środowiskach współbieżnych.
Rozpocznij okresy prób ponownego połączenia co najmniej 1 sekundę po wystąpieniu błędu.
Wyświetlanie i zmienianie limitów użycia oraz zwiększanie limitu
Aby wyświetlić lub zmienić limity wykorzystania w projekcie albo poprosić o zwiększenie limitu, wykonaj te czynności:
- Jeśli nie masz jeszcze konta rozliczeniowego dla swojego 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.
Żądania zbiorcze
Zachęcamy do korzystania z wsadów, ale większe wsady mogą powodować ograniczenie szybkości. Nie zalecamy wysyłania partii większych niż 50 żądań. Informacje o wysyłaniu żądań zbiorczych znajdziesz w artykule Wysyłanie żądań zbiorczych.