Коды ошибок FCM

Коды ошибок REST для HTTP v1 API

Ответы на ошибки HTTP для API HTTP версии 1 содержат код ошибки, сообщение об ошибке и статус ошибки. Они также могут содержать массив details с дополнительной информацией об ошибке.

Ниже приведены два примера ответов с ошибками.

Пример 1. Ответ об ошибке на запрос к API HTTP версии 1 с недопустимым значением в сообщении с данными

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "message.data[0].value",
            "description": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12"
          }
        ]
      }
    ]
  }
}

Пример 2. Ответ с ошибкой на запрос к HTTP v1 API с недействительным токеном регистрации

{
  "error": {
    "code": 400,
    "message": "The registration token is not a valid FCM registration token",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
        "errorCode": "INVALID_ARGUMENT"
      }
    ]
   }
}

Обратите внимание, что у обоих сообщений одинаковые код и статус, но массив details содержит значения разных типов. В первом примере тип type.googleapis.com/google.rpc.BadRequest указывает на ошибку в значениях запроса. Во втором примере с типом type.googleapis.com/google.firebase.fcm.v1.FcmError приведена ошибка, относящаяся к FCM. Для многих ошибок массив details содержит информацию, которая поможет вам выполнить отладку и устранить проблему.

В таблице ниже перечислены коды ошибок FCM v1 REST API и их описания.

Код ошибки	Описание и инструкции по устранению неполадок
UNSPECIFIED_ERROR Дополнительной информации об этой ошибке нет.	Нет.
INVALID_ARGUMENT (код ошибки HTTP = 400). Недопустимые параметры запроса. Возвращается расширение типа google.rpc.BadRequest, чтобы указать, какое поле было недействительным.	Возможные причины: недействительная регистрация, недействительное название пакета, слишком большой размер сообщения, недействительный ключ данных, недействительное время жизни или другие недействительные параметры. Недействительная регистрация. Проверьте формат токена регистрации, который вы передаете на сервер. Убедитесь, что он совпадает с токеном регистрации, который клиентское приложение получает при регистрации в FCM. Не усекайте токен и не добавляйте в него дополнительные символы. Недопустимое название пакета. Убедитесь, что сообщение было адресовано токену регистрации, название пакета которого совпадает со значением, переданным в запросе. Message too big. Проверьте, не превышает ли общий размер полезной нагрузки в сообщении ограничения FCM: 4096 байт для большинства сообщений или 2048 байт для сообщений, отправляемых в темы. Это касается как ключей, так и значений. Недопустимый ключ данных. Убедитесь, что полезная нагрузка не содержит ключ, который используется FCM для внутренних целей (например, from, gcm или любое значение с префиксом google). Обратите внимание, что некоторые слова (например, collapse_key) также используются FCM, но разрешены в полезной нагрузке. В этом случае значение полезной нагрузки будет переопределено значением FCM. Недопустимое значение TTL. Убедитесь, что значение, указанное в параметре ttl, является целым числом, представляющим продолжительность в секундах в диапазоне от 0 до 2 419 200 (4 недели). Недопустимые параметры. Убедитесь, что у указанных параметров правильные названия и типы.
UNREGISTERED (код ошибки HTTP – 404). Экземпляр приложения не зарегистрирован в FCM. Обычно это означает, что использованный токен больше недействителен и нужно использовать новый.	Эта ошибка может быть вызвана отсутствием токенов регистрации или незарегистрированными токенами. Отсутствует регистрация. Если целевой объект сообщения – это значение token, убедитесь, что запрос содержит токен регистрации. Not registered. Токен регистрации может стать недействительным в следующих случаях: - Клиентское приложение отменило регистрацию в FCM. - Если регистрация клиентского приложения автоматически отменена, что может произойти, если пользователь удалит приложение. Например, в iOS, если служба обратной связи APNs сообщила, что токен APNs недействителен. - Если срок действия токена регистрации истек (например, Google может решить обновить токены регистрации или истек срок действия токена APN для iOS-устройств). - Если клиентское приложение обновлено, но новая версия не настроена на получение сообщений. Во всех этих случаях удалите токен регистрации с сервера приложений и прекратите использовать его для отправки сообщений.
SENDER_ID_MISMATCH (код ошибки HTTP = 403). Идентификатор отправителя, прошедшего аутентификацию, отличается от идентификатора отправителя для токена регистрации.	Токен регистрации связан с определенной группой отправителей. При регистрации клиентского приложения в FCM необходимо указать, каким отправителям разрешено отправлять сообщения. При отправке сообщений в клиентское приложение следует использовать один из этих идентификаторов отправителя. Если вы переключитесь на другой идентификатор, существующие токены регистрации перестанут работать.
QUOTA_EXCEEDED (код ошибки HTTP = 429). Превышено ограничение на отправку для целевого адреса сообщения. Возвращается расширение типа google.rpc.QuotaFailure, указывающее, какая квота была превышена.	Эта ошибка может быть вызвана превышением квоты на частоту отправки сообщений, квоты на частоту отправки сообщений устройством или квоты на частоту отправки сообщений в тему. Превышена частота отправки сообщений. Сообщения отправляются слишком часто. Вам необходимо снизить общую скорость отправки писем. Используйте экспоненциальную выдержку с минимальной начальной задержкой в 1 минуту, чтобы повторно отправлять отклоненные сообщения. Превышена частота отправки сообщений на устройство. Сообщения отправляются на определенное устройство слишком часто. Подробнее об ограничении скорости передачи сообщений на одно устройство… Уменьшите количество сообщений, отправляемых на это устройство, и используйте экспоненциальную выдержку для повторной отправки. Превышена частота сообщений по теме. Частота сообщений подписчикам по определенной теме слишком высока. Уменьшите количество сообщений, отправляемых по этой теме, и используйте экспоненциальную выдержку с минимальной начальной задержкой в одну минуту, чтобы повторить отправку.
UNAVAILABLE (код ошибки HTTP – 503). Сервер перегружен.	Сервер не смог обработать запрос вовремя. Повторите тот же запрос, но при этом: – учитывайте заголовок Retry-After, если он включен в ответ от сервера подключения FCM; - Реализуйте экспоненциальную выдержку в механизме повторных попыток. (например, если вы подождали одну секунду перед первой попыткой, подождите не менее двух секунд перед следующей, затем четыре секунды и т.д.). Если вы отправляете несколько сообщений, рекомендуем использовать джиттеринг. Дополнительную информацию вы найдете в разделе обработки повторных попыток.Вы также можете проверить панель мониторинга FCM, чтобы узнать, не возникли ли в работе сервиса сбои, которые могут повлиять на FCM. Отправители, которые вызывают проблемы, рискуют попасть в черный список.
INTERNAL (код ошибки HTTP – 500). Произошла неизвестная внутренняя ошибка.	При обработке запроса произошла ошибка сервера. Вы можете повторить запрос, следуя рекомендациям из раздела Повторные попытки , или проверить панель мониторинга FCM. чтобы узнать, есть ли сбои в работе FCM. Если ошибка не исчезнет, обратитесь в службу поддержки Firebase.
THIRD_PARTY_AUTH_ERROR (код ошибки HTTP = 401). Сертификат APNs или ключ авторизации для push-уведомлений в браузере недействителен или отсутствует.	Не удалось отправить сообщение, предназначенное для iOS-устройства или веб-push-регистрации. Проверьте действительность учетных данных для разработки и производства.

Коды ошибок Admin SDK

В таблице ниже перечислены коды ошибок Firebase Admin FCM API и их описания, а также рекомендации по устранению.

Код ошибки	Описание и инструкции по устранению неполадок
messaging/invalid-argument	Методу FCM был передан недопустимый аргумент. В сообщении об ошибке должна быть дополнительная информация.
messaging/invalid-recipient	Недействительный получатель сообщения. В сообщении об ошибке должна быть дополнительная информация.
messaging/invalid-payload	Указан недопустимый объект полезной нагрузки сообщения. В сообщении об ошибке должна быть дополнительная информация.
messaging/invalid-data-payload-key	Полезная нагрузка сообщения с данными содержит недопустимый ключ. Список ключей, которые нельзя использовать, приведен в справочной документации по DataMessagePayload.
messaging/payload-size-limit-exceeded	Размер полезной нагрузки сообщения превышает ограничение (FCM). Для большинства сообщений ограничение составляет 4096 байт. Для сообщений, отправляемых в темы, ограничение составляет 2048 байт. Общий размер полезной нагрузки включает как ключи, так и значения.
messaging/invalid-options	Указан недопустимый объект параметров сообщения. В сообщении об ошибке должна быть дополнительная информация.
messaging/invalid-registration-token	Указан недопустимый токен регистрации. Убедитесь, что он совпадает с токеном регистрации, который клиентское приложение получает при регистрации в FCM. Не обрезайте и не добавляйте к нему символы.
messaging/registration-token-not-registered	Указанный токен регистрации не зарегистрирован. Ранее действительный токен регистрации может быть отменен по разным причинам, в том числе: Клиентское приложение отменило регистрацию в FCM. Регистрация клиентского приложения была автоматически отменена. Это может произойти, если пользователь удалит приложение или если сервис обратной связи APNs сообщит, что токен APNs недействителен (на платформах Apple). Срок действия токена регистрации истек. Например, Google может решить обновить токены регистрации, а для устройств Apple может истечь срок действия токена APNs. Клиентское приложение было обновлено, но новая версия не настроена на получение сообщений. Во всех этих случаях удалите токен регистрации и прекратите использовать его для отправки сообщений.
messaging/invalid-package-name	Сообщение было адресовано токену регистрации, название пакета которого не соответствует указанному параметру restrictedPackageName.
messaging/message-rate-exceeded	Слишком высокая частота отправки сообщений определенному получателю. Уменьшите количество сообщений, отправляемых на это устройство или в тему, и не пытайтесь сразу же повторно отправить сообщение.
messaging/device-message-rate-exceeded	Частота отправки сообщений на определенное устройство слишком высока. Уменьшите количество сообщений, отправляемых на это устройство, и не пытайтесь сразу же повторить отправку.
messaging/topics-message-rate-exceeded	Слишком высокая частота отправки сообщений подписчикам определенной темы. Уменьшите количество сообщений, отправляемых по этой теме, и не пытайтесь сразу же повторить отправку.
messaging/topics-subscription-rate-exceeded	Слишком высокая частота запросов на управление подпиской для определенной темы. Уменьшите количество запросов по этой теме и не пытайтесь отправить запрос повторно сразу после ошибки.
messaging/too-many-topics	Токен регистрации подписан на максимальное количество тем и не может быть подписан на другие.
messaging/invalid-apns-credentials	Сообщение, предназначенное для устройства Apple, не удалось отправить, поскольку требуемый SSL-сертификат APNs не был загружен или срок его действия истек. Проверьте срок действия сертификатов для разработки и рабочей среды.
messaging/mismatched-credential	У учетных данных, использованных для аутентификации этого SDK, нет разрешения на отправку сообщений на устройство, соответствующее предоставленному токену регистрации. Убедитесь, что учетные данные и токен регистрации относятся к одному проекту Firebase. Информацию о том, как аутентифицировать Firebase Admin SDK, можно найти в статье Как добавить Firebase в приложение.
messaging/authentication-error	SDK не удалось выполнить аутентификацию на серверах FCM. Убедитесь, что вы аутентифицируете Firebase Admin SDK с помощью учетных данных, у которых есть необходимые разрешения для отправки сообщений FCM. Информацию о том, как аутентифицировать Firebase Admin SDK, можно найти в статье Как добавить Firebase в приложение.
messaging/server-unavailable	Сервер FCM не смог обработать запрос вовремя. Повторите тот же запрос, но: Учитывайте заголовок Retry-After, если он включен в ответ от сервера подключений FCM. Реализуйте в механизме повторных попыток экспоненциальную выдержку. Например, если вы подождали одну секунду перед первой повторной попыткой, подождите не менее двух секунд перед следующей, затем четыре секунды и продолжайте увеличивать интервал. Если вы отправляете несколько сообщений, задержите каждое из них на дополнительное случайное время, чтобы не отправлять новый запрос для всех сообщений одновременно. Отправители, которые вызывают проблемы, рискуют попасть в черный список.
messaging/internal-error	При обработке запроса на сервере FCM произошла ошибка. Вы можете повторить запрос, следуя требованиям, указанным в строке messaging/server-unavailable. Если ошибка не исчезнет, сообщите о ней в службу поддержки.
messaging/unknown-error	Возникла неизвестная ошибка сервера. Подробные сведения можно найти в необработанном ответе сервера в сообщении об ошибке. Если вы получили такое сообщение об ошибке, отправьте его полный текст в отчет об ошибке.