Коды ошибок 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 | Предоставленный регистрационный токен не зарегистрирован. Ранее действительный регистрационный токен может быть отменён по ряду причин, включая:
|
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 не смог обработать запрос вовремя. Вам следует повторить тот же запрос, но для этого необходимо:
|
messaging/internal-error | Сервер FCM обнаружил ошибку при попытке обработки запроса. Вы можете повторить тот же запрос, следуя инструкциям, указанным в предыдущей строке messaging/server-unavailable . Если ошибка не исчезнет, сообщите о ней в службу поддержки Bug Report . |
messaging/unknown-error | Возвращена неизвестная ошибка сервера. Подробнее см. необработанный ответ сервера в сообщении об ошибке. Если вы получили эту ошибку, отправьте полное сообщение об ошибке в нашу службу поддержки Bug Report . |