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"
}
}
Чтобы исправить эту ошибку:
- Посетите консоль API Google
- Выберите свой проект.
- Перейдите на вкладку «Квоты» .
- Запросить дополнительную квоту. Подробнее см. в разделе Запросить дополнительную квоту .
Дополнительную информацию об ограничениях 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 означает, что пользователь достиг максимального количества запросов Gmail API. Это ограничение зависит от типа запросов. Ниже приведено 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 «User-rate limit exceeded» «(Mail sending)» с указанием времени на повторную попытку. Обратите внимание, что превышение суточных ограничений может привести к появлению подобных ошибок в течение нескольких часов, прежде чем запрос будет принят.
Конвейер отправки почты сложен: как только пользователь превышает свою квоту, может возникнуть задержка в несколько минут, прежде чем API начнёт возвращать ответы с кодом ошибки 429. Поэтому нельзя предполагать, что ответ 200 означает успешную отправку письма.
Ограничения пропускной способности
API устанавливает ограничения на исходящую и исходящую пропускную способность для каждого пользователя, которые аналогичны ограничениям IMAP, но не зависят от него. Эти ограничения действуют для всех клиентов Gmail API для данного пользователя.
Эти ограничения обычно достигаются только в исключительных или злоупотребляющих ситуациях. При превышении этих ограничений возвращается ошибка HTTP 429 Too Many Requests «User-rate limit exceeded» с указанием времени на повторную попытку. Обратите внимание, что превышение дневных ограничений может привести к появлению подобных ошибок в течение нескольких часов, прежде чем запрос будет принят.
Одновременные запросы
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 запросов не рекомендуется. Информация о пакетной обработке запросов приведена в разделе Пакетная обработка запросов .