Эта страница переведена с помощью Cloud Translation API.

Устранить ошибки

API Gmail возвращает информацию об ошибках двух уровней:

Коды и сообщения об ошибках HTTP в заголовке.
В теле ответа содержится JSON-объект с дополнительными сведениями, которые помогут определить, как обработать ошибку.

Ваше приложение Gmail должно перехватывать и обрабатывать все ошибки, которые могут возникнуть при использовании REST API. В этом руководстве приведены инструкции по устранению конкретных ошибок API Gmail.

Сводка кодов состояния HTTP

Код ошибки	Описание
`200 - OK`	Запрос выполнен успешно (это стандартный ответ для успешных HTTP-запросов).
`400 - Bad Request`	Запрос не может быть выполнен из-за ошибки, допущенной клиентом.
`401 - Unauthorized`	Запрос содержит неверные учетные данные.
`403 - Forbidden`	Запрос получен и понят, но у пользователя нет разрешения на его выполнение.
`404 - Not Found`	Запрошенная страница не найдена.
`429 - Too Many Requests`	Слишком много запросов к API.
`500, 502, 503, 504 - Server Errors`	При обработке запроса возникла непредвиденная ошибка.

400 ошибок

Эти ошибки означают, что запрос содержит ошибку, часто из-за отсутствия обязательного параметра.

`badRequest`

Эта ошибка может возникнуть из-за любой из следующих проблем в вашем коде:

Не указано обязательное поле или параметр.
Указанное значение или комбинация указанных полей недопустимы.
Вложение недействительно.

Приведенный ниже пример 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 ошибок

Эти ошибки означают, что запрос не содержит действительного токена доступа.

`authError`

Эта ошибка возникает, когда используемый вами токен доступа просрочен или недействителен. Также причиной может быть отсутствие авторизации для запрошенных областей действия. Следующий пример в формате JSON иллюстрирует эту ошибку:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization",
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

Для устранения этой ошибки обновите токен доступа, используя долгосрочный токен обновления. Если вы используете клиентскую библиотеку, она автоматически обрабатывает обновление токена. Если это не удается, направьте пользователя через процесс OAuth, как описано в разделе «Узнайте больше об аутентификации и авторизации» .

Дополнительную информацию об ограничениях Gmail см. в разделе «Ограничения использования» .

403 ошибки

Эти ошибки возникают при превышении лимита использования или при отсутствии у пользователя необходимых прав. Чтобы определить причину, оцените поле reason в возвращаемом JSON-файле. Эта ошибка возникает в следующих ситуациях:

Ваше приложение нельзя использовать в домене авторизованного пользователя.
Суточный лимит был превышен.
Превышен лимит количества запросов от пользователей.
Лимит ставок по проекту был превышен.

Для получения более подробной информации см. раздел «Ограничения использования» .

`dailyLimitExceeded`

Эта ошибка возникает, когда достигнут лимит API для вашего проекта. Следующий пример JSON иллюстрирует эту ошибку:

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

Эта ошибка возникает, когда владелец приложения установил лимит квоты для ограничения использования определенного ресурса. Для устранения этой ошибки увеличьте квоту в проекте Google Cloud. Дополнительную информацию см. в разделе «Управление лимитами квот» .

`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.
Попросите пользователя связаться со своим администратором домена, чтобы запросить доступ к вашему приложению.

`rateLimitExceeded`

Эта ошибка указывает на то, что пользователь достиг максимального количества запросов к API Gmail. Этот лимит варьируется в зависимости от типа запроса. Следующий пример JSON иллюстрирует эту ошибку:

{
  "error": {
  "errors": [
    {
    "domain": "usageLimits",
    "message": "Rate Limit Exceeded",
    "reason": "rateLimitExceeded",
    }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
  }
}

Чтобы исправить эту ошибку, попробуйте следующее:

Запросить увеличение квоты .
Используйте экспоненциальную задержку для повторной отправки запроса.

`userRateLimitExceeded`

Эта ошибка возникает, когда достигнут лимит на одного пользователя. Следующий пример в формате JSON иллюстрирует эту ошибку:

{
  "error": {
  "errors": [
    {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
    }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
  }
}

Для устранения этой ошибки попробуйте оптимизировать код приложения, уменьшив количество запросов, или используйте экспоненциальную задержку для повторной отправки запроса.

429 ошибок

Ошибка 429 «Слишком много запросов» может возникать из-за ежедневных лимитов на пользователя (включая лимиты на отправку почты), лимитов пропускной способности или лимита на количество одновременных запросов для каждого пользователя. Информация о каждом лимите приведена ниже. Однако каждый лимит можно устранить либо путем повторной отправки неудачных запросов , либо путем распределения обработки между несколькими учетными записями Gmail.

Ограничения для каждого пользователя не могут быть увеличены ни по какой причине. Для получения дополнительной информации об ограничениях см. раздел «Ограничения использования» .

Ограничения на отправку почты

API Gmail устанавливает стандартные ежедневные лимиты на отправку почты. Эти лимиты различаются для платных пользователей Google Workspace и пользователей пробной версии gmail.com. Информацию об этих лимитах см. в разделе «Лимиты отправки Gmail в Google Workspace» .

Эти ограничения действуют для каждого пользователя и распространяются на все его клиенты, будь то API-клиенты, встроенные или веб-клиенты, или SMTP MSA. При превышении этих лимитов возвращается ошибка HTTP 429 "Слишком много запросов: превышен лимит скорости запросов пользователя (отправка почты)" с указанием времени повторной попытки. Превышение суточных лимитов может привести к появлению этих ошибок в течение нескольких часов, прежде чем запрос будет принят.

Процесс отправки почты сложен: как только пользователь превышает свою квоту, может возникнуть задержка в несколько минут, прежде чем API начнет возвращать ошибки 429. Нельзя предполагать, что ответ 200 означает успешную отправку письма.

Ограничения пропускной способности

API устанавливает для каждого пользователя ограничения на пропускную способность для загрузки и скачивания, которые равны, но не зависят от протокола IMAP. Эти ограничения действуют для всех клиентов Gmail API для данного пользователя.

Эти лимиты обычно достигаются только в исключительных или неправомерных ситуациях. При превышении этих лимитов возвращается ошибка HTTP 429 "Слишком много запросов: превышен лимит скорости запросов пользователей" с указанием времени повторной попытки. Превышение суточных лимитов может привести к появлению этих ошибок в течение нескольких часов, прежде чем запрос будет принят.

Одновременные запросы

API Gmail устанавливает ограничение на количество одновременных запросов для каждого пользователя (в дополнение к ограничению на количество запросов для каждого пользователя). Это ограничение распространяется на все клиенты API Gmail, обращающиеся к пользователю, и гарантирует, что ни один клиент API не перегружает почтовый ящик пользователя Gmail или его серверную часть.

Выполнение множества параллельных запросов к одному пользователю или отправка пакетов с большим количеством запросов может вызвать эту ошибку. Большое количество независимых API-клиентов, одновременно обращающихся к почтовому ящику пользователя Gmail, также может вызвать эту ошибку. Если этот лимит превышен, возвращается ошибка HTTP 429 "Слишком много запросов: слишком много одновременных запросов к пользователю".

ошибки 500, 502, 503, 504

Эти ошибки возникают, когда во время обработки запроса происходит непредвиденная ошибка сервера. Причиной таких ошибок могут быть различные проблемы, включая совпадение времени выполнения запроса с другим запросом или запрос на неподдерживаемое действие, например, попытка обновить разрешения для отдельной страницы в Google Sites вместо всего сайта.

Ниже приведён список ошибок 5xx:

Ошибка бэкэнда 500
502 Неверный шлюз
Сервис 503 недоступен
504 Таймаут шлюза

backendError

Эта ошибка возникает, когда при обработке запроса появляется непредвиденная ошибка. Следующий пример в формате JSON иллюстрирует эту ошибку:

{
  "error": {
  "errors": [
    {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
    }
  ],
  "code": 500,
  "message": "Backend Error"
  }
}

Для устранения этой ошибки используйте экспоненциальную задержку для повторной отправки запроса.

Повторите неудачные запросы для устранения ошибок.

Для обработки ошибок, связанных с ограничениями скорости, объемом сети или временем ответа, можно периодически повторять неудачный запрос с увеличивающимся интервалом времени. Например, можно повторить неудачный запрос через одну секунду, затем через две секунды, а затем через четыре секунды. Этот метод называется экспоненциальной задержкой и используется для повышения эффективности использования полосы пропускания и максимизации пропускной способности запросов в средах с параллельным выполнением.

Повторные попытки следует начинать не позднее чем через одну секунду после возникновения ошибки.

Управление лимитами квот

Чтобы просмотреть или изменить лимиты использования для вашего проекта, или запросить увеличение квоты, выполните следующие действия:

Если у вас еще нет платежного аккаунта для вашего проекта, создайте его.
Перейдите на страницу «Включенные API» в библиотеке API в консоли API и выберите API из списка.
Чтобы просмотреть и изменить настройки, связанные с квотами, выберите «Квоты» . Чтобы просмотреть статистику использования, выберите «Использование» .

Для получения более подробной информации см. раздел «Просмотр и управление квотами» .

Пакетные запросы

Рекомендуется использовать пакетные запросы; однако, при больших размерах пакетов, скорее всего, будет применено ограничение скорости. Не рекомендуется отправлять пакеты, содержащие более 50 запросов. Информацию о том, как отправлять пакетные запросы, см. в разделе «Пакетные запросы» .