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.
Aplikacje Gmaila powinny 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 API.
Rozwiązywanie błędu 400: nieprawidłowe żądanie
Ten błąd może być spowodowany tymi błędami w kodzie:
- Nie podano wymaganego pola ani parametru.
- Podana wartość lub kombinacja podanych pól jest nieprawidłowa.
- Nieprawidłowy załącznik.
Poniżej znajdziesz przykładową reprezentację 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 logowania
Błąd 401 oznacza, że 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żej znajduje się reprezentacja JSON tego błędu:
{
"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 opisany w artykule Autoryzowanie aplikacji w Gmailu.
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity użytkowania.
Rozwiązywanie błędu 403: przekroczono limit wykorzystania
Błąd 403 występuje, gdy limit wykorzystania został przekroczony lub użytkownik nie ma odpowiednich uprawnień. Aby określić konkretny typ błędu, sprawdź pole reason zwróconego kodu JSON. Ten błąd występuje w tych sytuacjach:
- Przekroczono limit dzienny.
- Przekroczono limit użytkownika.
- Przekroczono limit projektu.
- Nie można używać aplikacji w domenie uwierzytelnionego użytkownika.
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity użytkowania.
Rozwiązywanie błędu 403: przekroczono dzienny limit
Błąd dailyLimitExceeded oznacza, że osiągnięto limit interfejsu API w ramach bezpłatnego okresu próbnego w Twoim projekcie. Poniżej znajduje się reprezentacja JSON tego błędu:
{
"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 użytkowania.
Rozwiązywanie błędu 403: przekroczono limit na użytkownika
Błąd userRateLimitExceeded oznacza, że osiągnięto limit liczby żądań na użytkownika. Poniżej znajduje się reprezentacja JSON tego błędu:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "userRateLimitExceeded",
"message": "User Rate Limit Exceeded"
}
],
"code": 403,
"message": "User Rate Limit Exceeded"
}
}
Aby naprawić ten błąd, spróbuj zoptymalizować kod aplikacji, aby wysyłać mniej żądań lub ponawiać żądania. Więcej informacji o ponawianiu żądań znajdziesz w sekcji Ponawianie nieudanych żądań w celu rozwiązania błędów.
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity użytkowania.
Rozwiązywanie błędu 403: przekroczono limit częstotliwości
Błąd rateLimitExceeded oznacza, że użytkownik osiągnął maksymalną liczbę żądań interfejsu Gmail API. Limit ten zależy od rodzaju żądań.
Poniżej znajduje się reprezentacja JSON tego błędu:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Rate Limit Exceeded",
"reason": "rateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Aby naprawić ten błąd, ponów nieudane żądania.
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity użytkowania.
Rozwiązywanie błędu 403: Aplikacji o identyfikatorze {appId} nie można używać w domenie uwierzytelnionego użytkownika
Błąd domainPolicy występuje, gdy zasady domeny użytkownika nie zezwalają aplikacji na dostęp do Gmaila. Poniżej znajduje się reprezentacja JSON tego błędu:
{
"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.
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 poszczególnych limitach. Każdy limit można jednak rozwiązać, ponawiając nieudane żądania lub dzielą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 wymusza standardowe dzienne limity wysyłania e-maili. Te limity różnią się w przypadku użytkowników płatnych Google Workspace i użytkowników wersji próbnej Google Workspace gmail.com. 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, klienci natywni/internetowi czy serwery SMTP MSA. Jeśli te limity zostaną przekroczone, zwracany jest błąd HTTP 429 Too Many Requests „User-rate limit exceeded” (Przekroczono limit liczby żądań użytkownika) „(Mail sending)” (Wysyłanie e-maili)Too Many Requests z czasem ponowienia próby.
Pamiętaj, że przekroczenie dziennych limitów może powodować tego typu 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 o błędzie 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 przesyłania i pobierania danych na użytkownika, które są równe limitom IMAP, ale od nich niezależne. Te limity są wspólne dla wszystkich klientów interfejsu Gmail API danego użytkownika.
Limity te 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” (Przekroczono limit liczby żądań użytkownika) z informacją o czasie, po którym można ponowić próbę.
Pamiętaj, że przekroczenie dziennych limitów może powodować tego typu błędy przez wiele godzin, zanim żądanie zostanie zaakceptowane.
Równoczesne żądania
Interfejs Gmail API wymusza 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 Gmail API, którzy mają dostęp do danego użytkownika. Dzięki temu żaden klient interfejsu API nie przeciąża skrzynki pocztowej użytkownika Gmaila ani jego serwera backendu.
Ten błąd może wystąpić, gdy wyślesz wiele równoległych żądań dotyczących jednego użytkownika lub wyślesz partie 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 Too Many Requests„Too many concurrent requests for user” (Za dużo jednoczesnych żądań użytkownika).
Rozwiązywanie błędu 500: błąd backendu
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, ponów nieudane żądania. Poniżej znajduje się lista błędów 500:
- 502 Nieprawidłowa brama
- 503 Usługa niedostępna
- 504 Przekroczono limit czasu bramy
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 1 sekundzie, potem po 2 sekundach, a następnie po 4 sekundach. Ta metoda jest nazywana wykładniczym wycofywaniem i służy do poprawy wykorzystania przepustowości oraz maksymalizacji przepustowości żądań w środowiskach współbieżnych.
Okresy ponawiania powinny rozpoczynać się co najmniej sekundę po wystąpieniu błędu.
Wyświetlanie i zmienianie limitów wykorzystania, zwiększanie limitu
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żytkowanie.
Żądania zbiorcze
Zalecamy korzystanie z przetwarzania wsadowego, ale większe rozmiary wsadu mogą spowodować ograniczenie liczby żądań. Nie zalecamy wysyłania partii zawierających więcej niż 50 żądań. Informacje o tym, jak wysyłać żądania zbiorcze, znajdziesz w artykule Wysyłanie żądań zbiorczych.