Коды ошибок FCM

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

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

Вот два примера ответов об ошибках:

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

{
  "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 , указывающее, какое поле было недействительным. Возможные причины: недействительная регистрация, неверное имя пакета, слишком большое сообщение, недействительный ключ данных, недействительный TTL или другие недействительные параметры.
Неверная регистрация : проверьте формат регистрационного токена, передаваемого на сервер. Убедитесь, что он совпадает с регистрационным токеном, который клиентское приложение получает при регистрации в FCM. Не обрезайте токен и не добавляйте дополнительные символы.
Недопустимое имя пакета : убедитесь, что сообщение адресовано регистрационному токену, имя пакета которого соответствует значению, переданному в запросе.
Слишком большое сообщение : убедитесь, что общий размер данных, включённых в сообщение, не превышает ограничений FCM: 4096 байт для большинства сообщений или 2048 байт для сообщений в темах. Это включает как ключи, так и значения.
Недопустимый ключ данных : убедитесь, что данные полезной нагрузки не содержат ключа (например, from, gcm или любого значения с префиксом Google), используемого FCM внутри. Обратите внимание, что некоторые слова (например, coll_key) также используются FCM, но разрешены в полезной нагрузке. В этом случае значение полезной нагрузки будет переопределено значением FCM.
Недопустимый TTL : убедитесь, что значение, используемое в ttl, является целым числом, представляющим длительность в секундах от 0 до 2 419 200 (4 недели).
Недопустимые параметры : проверьте, что предоставленные параметры имеют правильное имя и тип.
UNREGISTERED (код ошибки HTTP = 404). Экземпляр приложения был отменён в FCM. Обычно это означает, что используемый токен больше недействителен и необходимо использовать новый. Эта ошибка может быть вызвана отсутствием регистрационных токенов или незарегистрированными токенами.
Отсутствует регистрация : если целью сообщения является значение token , проверьте, содержит ли запрос токен регистрации.
Не зарегистрирован : существующий регистрационный токен может перестать быть действительным в ряде случаев, включая:
- Если клиентское приложение отменяет регистрацию в FCM.
– Если клиентское приложение автоматически отменяет регистрацию, что может произойти, если пользователь удаляет приложение. Например, на iOS, если служба обратной связи APNs сообщила, что токен APNs недействителен.
- Если срок действия регистрационного токена истек (например, Google может решить обновить регистрационные токены или срок действия токена APNs истек для устройств iOS).
- Если клиентское приложение обновлено, но новая версия не настроена на прием сообщений.
Во всех этих случаях удалите этот регистрационный токен с сервера приложения и прекратите его использовать для отправки сообщений.
SENDER_ID_MISMATCH (код ошибки HTTP = 403) Идентификатор аутентифицированного отправителя отличается от идентификатора отправителя для регистрационного токена. Регистрационный токен привязан к определённой группе отправителей. При регистрации клиентского приложения в FCM оно должно указать, каким отправителям разрешено отправлять сообщения. При отправке сообщений в клиентское приложение следует использовать один из этих идентификаторов отправителя. При переключении на другого отправителя существующие регистрационные токены перестанут работать.
QUOTA_EXCEEDED (код ошибки HTTP = 429) Превышен лимит отправки для целевого объекта сообщения. Возвращается расширение типа google.rpc.QuotaFailure , указывающее, какая квота была превышена. Эта ошибка может быть вызвана превышением квоты на частоту сообщений, превышением квоты на частоту сообщений устройства или превышением квоты на частоту сообщений темы.
Превышена скорость отправки сообщений : Скорость отправки сообщений слишком высокая. Необходимо снизить общую скорость отправки сообщений. Используйте экспоненциальную задержку с минимальной начальной задержкой в ​​1 минуту для повторной отправки отклонённых сообщений.
Превышена скорость отправки сообщений на устройство : скорость отправки сообщений на определённое устройство слишком высока. См. ограничение скорости отправки сообщений на одно устройство . Уменьшите количество сообщений, отправляемых на это устройство, и используйте экспоненциальную задержку для повторной отправки.
Превышена скорость отправки сообщений по теме : Скорость отправки сообщений подписчикам определённой темы слишком высока. Уменьшите количество сообщений, отправляемых по этой теме, и используйте экспоненциальную задержку с минимальной начальной задержкой в ​​1 минуту для повторной отправки.
UNAVAILABLE (код ошибки HTTP = 503) Сервер перегружен. Сервер не смог обработать запрос вовремя. Повторите тот же запрос, но для этого вам необходимо:
- Учитывать заголовок Retry-After, если он включен в ответ от сервера соединений FCM.
– Реализуйте экспоненциальную задержку в механизме повторных попыток (например, если вы ждали одну секунду перед первой повторной попыткой, подождите не менее двух секунд перед следующей, затем 4 секунды и т. д.). При отправке нескольких сообщений рассмотрите возможность применения джиттера. Подробнее см. в разделе «Обработка повторных попыток» или проверьте панель состояния FCM , чтобы определить, есть ли какие-либо текущие сбои в работе сервиса, влияющие на FCM. Отправители, создающие проблемы, могут быть занесены в список заблокированных.
INTERNAL (код ошибки HTTP = 500) Произошла неизвестная внутренняя ошибка. Сервер обнаружил ошибку при попытке обработки запроса. Вы можете повторить тот же запрос, следуя рекомендациям в разделе «Обработка повторных попыток» или проверив панель состояния FCM , чтобы определить, есть ли какие-либо текущие сбои в работе FCM. Если ошибка повторяется, обратитесь в службу поддержки Firebase.
THIRD_PARTY_AUTH_ERROR (код ошибки HTTP = 401) Сертификат APNs или ключ аутентификации web push-уведомлений недействителен или отсутствует. Не удалось отправить сообщение, предназначенное для устройства iOS, или push-заявку на веб-уведомление. Проверьте действительность ваших учётных данных для разработки и производства.

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

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

Код ошибки Описание и шаги решения
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 .
  • Клиентское приложение было автоматически дерегистрировано. Это могло произойти, если пользователь удалил приложение или, на платформах Apple, если служба обратной связи APNs сообщила, что токен APNs недействителен.
  • Срок действия регистрационного токена истёк. Например, Google может решить обновить регистрационные токены, или же срок действия токена APNs для устройств Apple может истечь.
  • Клиентское приложение обновлено, но новая версия не настроена на прием сообщений.
Во всех этих случаях удалите этот регистрационный токен и прекратите использовать его для отправки сообщений.
messaging/invalid-package-name Сообщение было адресовано регистрационному токену, имя пакета которого не соответствует предоставленной опции restrictedPackageName .
messaging/message-rate-exceeded Слишком высокая частота сообщений, отправляемых на это устройство или в эту тему. Уменьшите количество сообщений, отправляемых на это устройство или в эту тему, и не пытайтесь сразу же повторить отправку.
messaging/device-message-rate-exceeded Слишком высокая частота сообщений, отправляемых на это устройство. Уменьшите количество сообщений, отправляемых на это устройство, и не пытайтесь сразу же повторить отправку.
messaging/topics-message-rate-exceeded Слишком много сообщений подписчикам на определённую тему. Уменьшите количество сообщений, отправляемых по этой теме, и не пытайтесь сразу же повторить отправку.
messaging/too-many-topics Регистрационный токен подписан на максимальное количество тем и не может быть подписан ни на одну другую.
messaging/invalid-apns-credentials Не удалось отправить сообщение, предназначенное для устройства Apple, поскольку требуемый SSL-сертификат APN не был загружен или срок его действия истёк. Проверьте действительность ваших сертификатов разработки и производства.
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 . Если ошибка не исчезнет, ​​сообщите о ней в службу поддержки Bug Report .
messaging/unknown-error Возвращена неизвестная ошибка сервера. Подробнее см. необработанный ответ сервера в сообщении об ошибке. Если вы получили эту ошибку, отправьте полное сообщение об ошибке в нашу службу поддержки Bug Report .