Interfejs Gmail API zwraca informacje o błędach na 2 poziomach:
- Kody błędów HTTP i komunikaty w nagłówku.
- Obiekt JSON w treści odpowiedzi z dodatkowymi informacjami, które pomagają określić sposób postępowania z błędem.
Aplikacje Gmail powinny wychwytywać i obsługiwać wszystkie błędy, które mogą wystąpić podczas korzystania z interfejsu API REST. W tym przewodniku znajdziesz instrukcje naprawiania określonych błędów interfejsu API.
Jak naprawić błąd 400: nieprawidłowe żądanie
Ten błąd może wynikać z tych błędów w 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ładowa reprezentacja tego błędu w formacie JSON:
{
"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.
Jak naprawić błąd 401: nieprawidłowe dane logowania
Błąd 401 oznacza, że 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. Ten błąd występuje w postaci kodu 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, automatycznie obsługuje ona odświeżanie tokenów. Jeśli to się nie uda, przekieruj użytkownika przez proces OAuth zgodnie z opisem w artykule Autoryzacja aplikacji w Gmailu.
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity wykorzystania.
Naprawianie 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, oceń pole reason zwróconego pliku JSON. Ten błąd występuje w tych sytuacjach:
- Przekroczono limit dzienny.
- Przekroczono limit liczby żądań użytkownika.
- Przekroczono limit liczby żądań w projekcie.
- Twojej aplikacji nie można używać w domenie uwierzytelnionego użytkownika.
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity wykorzystania.
Jak naprawić błąd 403: przekroczono dzienny limit
Błąd dailyLimitExceeded oznacza, że w projekcie osiągnięto limit grzecznościowego interfejsu API. Ten błąd występuje w postaci kodu 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 o wysyłaniu prośby o dodatkowy limit.
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity wykorzystania.
Naprawianie błędu 403: przekroczono limit liczby użytkowników
Błąd userRateLimitExceeded oznacza, że limit na użytkownika został osiągnięty. Oto przykład 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 tak, by zmniejszyć liczbę żądań lub ponawiać żądania. Informacje 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 wykorzystania.
Jak naprawić błąd 403: przekroczono limit ruchu
Błąd rateLimitExceeded oznacza, że użytkownik osiągnął maksymalną częstotliwość żądań interfejsu Gmail API. Ten limit zależy od typu żądań.
Ten błąd występuje w postaci kodu JSON:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Rate Limit Exceeded",
"reason": "rateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Aby naprawić ten błąd, spróbuj ponownie wysłać nieudane żądania.
Więcej informacji o limitach Gmaila znajdziesz w artykule Limity wykorzystania.
Naprawianie błędu 403: aplikacji o identyfikatorze {appId} nie można używać w domenie uwierzytelnionego użytkownika
Błąd domainPolicy występuje, gdy zasada domeny użytkownika nie zezwala aplikacji na dostęp do Gmaila. Tak wygląda ten błąd 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 aplikacji na dostęp do Gmaila.
- Poproś użytkownika, aby skontaktował się z administratorem domeny i poprosił go o dostęp do aplikacji.
Usuwanie 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 równoczesnych żądań na użytkownika. Poniżej znajdziesz informacje o poszczególnych limitach. Każdy limit można jednak rozwiązać, próbując ponownie wysłać nieudane żądania, lub dzieląc przetwarzanie na kilka kont Gmail. Limitów na użytkownika nie można z żadnego powodu zwiększyć. Więcej informacji o limitach znajdziesz w artykule Limity wykorzystania.
Limity wysyłania poczty
Interfejs Gmail API wymusza standardowe dzienne limity wysyłania poczty. Limity te różnią się w przypadku użytkowników płacących Google Workspace i użytkowników korzystających z okresu próbnego gmail.com. Informacje o tych limitach znajdziesz w artykule Limity wysyłania Gmaila w Google Workspace.
Te limity dotyczą poszczególnych użytkowników i są wspólne dla wszystkich klientów użytkownika, niezależnie od tego, czy klienty interfejsu API, klienty natywne/internetowe czy MSA SMTP. Po przekroczeniu tych limitów zostanie zwrócony błąd HTTP 429 Too Many Requests „Przekroczono limit liczby żądań użytkownika (wysyłanie poczty)”.
Pamiętaj, że przekroczenie limitów dziennych może powodować występowanie tego typu błędów przez wiele godzin przed zaakceptowaniem żądania.
Potok wysyłania poczty jest złożony: gdy użytkownik przekroczy limit, może minąć kilka minut, zanim interfejs API zacznie zwracać odpowiedzi błędu 429. Nie możesz więc założyć, że odpowiedź 200 oznacza, że e-mail został wysłany.
Limity przepustowości
Interfejs API ma limity przepustowości dla przesyłania i pobierania na użytkownika. Są one równe, ale niezależne od IMAP. Limity te są wspólne dla wszystkich klientów interfejsu Gmail API dla danego użytkownika.
Limity te są zazwyczaj osiągane tylko w wyjątkowych lub niewłaściwych sytuacjach.
Po przekroczeniu tych limitów zwracany jest błąd HTTP 429 Too Many Requests
z informacją o czasie na ponowną próbę.
Pamiętaj, że przekroczenie limitów dziennych może powodować występowanie tego typu błędów przez wiele godzin przed zaakceptowaniem prośby.
Żądania równoczesne
Interfejs Gmail API egzekwuje 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 uzyskujących dostęp do danego użytkownika i gwarantuje, że żaden klient API nie przeciąża skrzynki pocztowej użytkownika Gmaila ani jego serwera backendu.
Ten błąd może wystąpić, gdy wykonywane jest wiele równoległych żądań dla jednego użytkownika lub wysyłanie grup z dużą liczbą żądań. Ten błąd może powodować także duża liczba niezależnych klientów API, którzy uzyskują dostęp do skrzynki pocztowej użytkownika Gmaila jednocześnie. W przypadku przekroczenia tego limitu zwracany jest błąd HTTP 429 Too Many Requests
„Zbyt wiele równoczesnych żądań użytkownika”.
Usuwanie 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, spróbuj ponownie wysłać nieudane żądania. Oto lista błędów 500:
- 502 Nieprawidłowa brama
- 503 Usługa niedostępna
- Przekroczenie limitu czasu bramy 504
Ponawianie nieudanych próśb w celu naprawienia błędów
Możesz co jakiś czas ponawiać nieudane żądanie przez dłuższy czas w celu obsługi błędów związanych z limitami liczby żądań, wielkością sieci lub czasem odpowiedzi. Możesz na przykład ponawiać nieudane żądanie po 1 sekundzie, następnie 2 sekundach i 4 sekundach. Ta metoda nazywa się wykładniczym ponawianiem i służy do poprawy wykorzystania przepustowości i zmaksymalizowania przepustowości żądań w równoczesnych środowiskach.
Okresy ponawiania powinny rozpoczynać się co najmniej 1 sekundę po wystąpieniu błędu.
Wyświetlanie i zmienianie limitów wykorzystania 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 powiązanego z projektem, utwórz je.
- Otwórz stronę Włączone interfejsy API w bibliotece interfejsów API w konsoli API i wybierz interfejs API z listy.
- Aby wyświetlić i zmienić ustawienia związane z limitami, wybierz Limity. Aby wyświetlić statystyki użytkowania, wybierz Użycie.
Żądania zbiorcze
Zalecamy korzystanie z grupowania, ale duże rozmiary wsadu prawdopodobnie spowodują ograniczenie liczby żądań. Nie zalecamy wysyłania wsadów większych niż 50 żądań. Informacje o tym, jak tworzyć żądania wsadowe, znajdziesz w artykule Tworzenie żądań wsadowych.