API Gmail возвращает два уровня информации об ошибках:
- Коды ошибок HTTP и сообщения в заголовке.
- Объект JSON в тексте ответа с дополнительными сведениями, которые помогут вам определить, как обработать ошибку.
Приложения Gmail должны улавливать и обрабатывать все ошибки, которые могут возникнуть при использовании REST API. В этом руководстве представлены инструкции по устранению конкретных ошибок API.
Устранение ошибки 400: неверный запрос
Эта ошибка может возникнуть из-за следующих ошибок вашего кода:
- Не указано обязательное поле или параметр.
- Указанное значение или комбинация предоставленных полей недействительны.
- Недопустимое вложение.
Ниже приведен пример представления этой ошибки в формате 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."
}
}
Чтобы исправить эту ошибку, проверьте поле message и соответствующим образом измените свой код.
Устраните ошибку 401: неверные учетные данные
Ошибка 401 означает, что используемый вами токен доступа просрочен или недействителен. Эта ошибка также может быть вызвана отсутствием авторизации для запрошенных областей. Ниже приведено JSON-представление этой ошибки:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "authError",
"message": "Invalid Credentials",
"locationType": "header",
"location": "Authorization",
}
],
"code": 401,
"message": "Invalid Credentials"
}
}
Чтобы исправить эту ошибку, обновите токен доступа, используя долгосрочный токен обновления. Если вы используете клиентскую библиотеку, она автоматически обрабатывает обновление токена. Если это не помогло, направьте пользователя через поток OAuth, как описано в разделе Авторизация вашего приложения с помощью Gmail .
Дополнительную информацию об ограничениях Gmail см. в разделе «Ограничения использования» .
Устраните ошибку 403: превышен лимит использования.
Ошибка 403 возникает, когда превышен лимит использования или у пользователя нет необходимых привилегий. Чтобы определить конкретный тип ошибки, оцените поле reason возвращаемого JSON. Эта ошибка возникает в следующих ситуациях:
- Дневной лимит превышен.
- Превышен лимит количества пользователей.
- Превышен лимит скорости проекта.
- Ваше приложение нельзя использовать в домене аутентифицированного пользователя.
Дополнительную информацию об ограничениях Gmail см. в разделе «Ограничения использования» .
Устраните ошибку 403: превышен дневной лимит.
Ошибка dailyLimitExceeded указывает на то, что достигнут лимит бесплатного API для вашего проекта. Ниже приведено JSON-представление этой ошибки:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "dailyLimitExceeded",
"message": "Daily Limit Exceeded"
}
],
"code": 403,
"message": "Daily Limit Exceeded"
}
}
Чтобы исправить эту ошибку:
- Посетите консоль Google API
- Выберите свой проект.
- Откройте вкладку «Квоты» .
- Запросите дополнительную квоту. Дополнительную информацию см. в разделе Запрос дополнительной квоты .
Дополнительную информацию об ограничениях Gmail см. в разделе «Ограничения использования» .
Устраните ошибку 403: превышен предел скорости пользователя.
Ошибка userRateLimitExceeded указывает на то, что достигнут предел для каждого пользователя. Ниже приведено JSON-представление этой ошибки:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "userRateLimitExceeded",
"message": "User Rate Limit Exceeded"
}
],
"code": 403,
"message": "User Rate Limit Exceeded"
}
}
Чтобы исправить эту ошибку, попробуйте оптимизировать код приложения, чтобы делать меньше запросов или повторять запросы. Информацию о повторных запросах см. в разделе Повтор неудачных запросов для устранения ошибок .
Дополнительную информацию об ограничениях Gmail см. в разделе «Ограничения использования» .
Устраните ошибку 403: превышен предел скорости.
rateLimitExceeded указывает на то, что пользователь достиг максимальной частоты запросов API Gmail. Этот лимит варьируется в зависимости от типа запросов. Ниже приведено JSON-представление этой ошибки:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Rate Limit Exceeded",
"reason": "rateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Чтобы исправить эту ошибку, повторите неудачные запросы .
Дополнительную информацию об ограничениях Gmail см. в разделе «Ограничения использования» .
Устраните ошибку 403: приложение с идентификатором {appId} нельзя использовать в домене аутентифицированного пользователя.
Ошибка domainPolicy возникает, когда политика домена пользователя не разрешает вашему приложению доступ к Gmail. Ниже приведено 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."
}
}
Чтобы исправить эту ошибку:
- Сообщите пользователю, что домен не разрешает вашему приложению доступ к Gmail.
- Попросите пользователя связаться с администратором домена, чтобы запросить доступ к вашему приложению.
Устраните ошибку 429: слишком много запросов
Ошибка 429 «Слишком много запросов» может возникнуть из-за ежедневных ограничений на количество пользователей (включая ограничения на отправку почты), ограничений пропускной способности или ограничения на количество одновременных запросов для каждого пользователя. Информация о каждом лимите приведена ниже. Однако каждое ограничение можно устранить, попытавшись повторить неудачные запросы или разделив обработку между несколькими учетными записями Gmail. Ограничения на пользователя не могут быть увеличены ни по какой причине. Дополнительные сведения об ограничениях см. в разделе Ограничения использования .
Ограничения на отправку почты
API Gmail применяет стандартные ограничения на ежедневную отправку почты. Эти ограничения различаются для платных пользователей Google Workspace и пробных пользователей gmail.com. Информацию об этих ограничениях см. в разделе «Ограничения на отправку Gmail» в Google Workspace .
Эти ограничения распространяются на каждого пользователя и являются общими для всех клиентов пользователя, будь то клиенты API, собственные/веб-клиенты или SMTP MSA. Если эти ограничения превышены, возвращается ошибка HTTP 429 Too Many Requests «Превышен предел скорости пользователя» «(Отправка почты)» с указанием времени для повторной попытки. Обратите внимание, что превышение дневных лимитов может привести к возникновению подобных ошибок в течение нескольких часов, прежде чем запрос будет принят.
Конвейер отправки почты сложен: как только пользователь превысит свою квоту, может возникнуть задержка в несколько минут, прежде чем API начнет возвращать 429 ответов с ошибками. Поэтому вы не можете предполагать, что ответ 200 означает, что электронное письмо было успешно отправлено.
Ограничения пропускной способности
API имеет ограничения пропускной способности загрузки и скачивания для каждого пользователя, которые равны, но не зависят от IMAP. Эти ограничения являются общими для всех клиентов API Gmail для данного пользователя.
Эти ограничения обычно нарушаются только в исключительных или злоупотребляющих ситуациях. Если эти ограничения превышены, возвращается ошибка HTTP 429 Too Many Requests «Превышен предел скорости пользователя» с указанием времени для повторной попытки. Обратите внимание, что превышение дневных лимитов может привести к возникновению подобных ошибок в течение нескольких часов, прежде чем запрос будет принят.
Параллельные запросы
API Gmail устанавливает ограничение на количество одновременных запросов для каждого пользователя (в дополнение к ограничению скорости для каждого пользователя). Это ограничение распространяется на все клиенты API Gmail, обращающиеся к данному пользователю, и гарантирует, что ни один клиент API не перегружает почтовый ящик пользователя Gmail или его внутренний сервер.
Эту ошибку может вызвать выполнение множества параллельных запросов для одного пользователя или отправка пакетов с большим количеством запросов. Эту ошибку также может вызвать большое количество независимых API-клиентов, одновременно обращающихся к почтовому ящику пользователя Gmail. Если этот предел превышен, возвращается ошибка HTTP 429 Too Many Requests «Слишком много одновременных запросов для пользователя».
Устранение ошибки 500: ошибка серверной части
backendError возникает, когда при обработке запроса возникает непредвиденная ошибка.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
Чтобы исправить эту ошибку, повторите неудачные запросы . Ниже приведен список из 500 ошибок:
- 502 Неверный шлюз
- 503 Сервис недоступен
- Ошибка 504 Время ответа сервера истекло
Повторите неудачные запросы, чтобы устранить ошибки.
Вы можете периодически повторять неудачный запрос в течение увеличенного периода времени, чтобы обрабатывать ошибки, связанные с ограничениями скорости, объемом сети или временем ответа. Например, вы можете повторить неудавшийся запрос через одну секунду, затем через две секунды, а затем через четыре секунды. Этот метод называется экспоненциальной задержкой и используется для улучшения использования полосы пропускания и максимизации пропускной способности запросов в параллельных средах.
Начинайте периоды повтора не позднее, чем через одну секунду после ошибки.
Просмотр или изменение лимитов использования, увеличение квоты
Чтобы просмотреть или изменить ограничения использования для вашего проекта или запросить увеличение квоты, выполните следующие действия:
- Если у вас еще нет платежного аккаунта для вашего проекта, создайте его.
- Посетите страницу «Включенные API» библиотеки API в консоли API и выберите API из списка.
- Чтобы просмотреть и изменить настройки, связанные с квотами, выберите «Квоты» . Чтобы просмотреть статистику использования, выберите «Использование» .
Пакетные запросы
Использование пакетной обработки приветствуется, однако большие размеры пакетов могут привести к ограничению скорости. Отправка пакетов размером более 50 запросов не рекомендуется. Информацию о пакетной обработке запросов см. в разделе Пакетная обработка запросов .