Коды ошибок REST для HTTP v1 API
Ответы об ошибках HTTP для HTTP v1 API содержат код ошибки, сообщение об ошибке и статус ошибки. Они также могут содержать массив 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, указывающее, какое поле было недопустимым. |
Возможные причины: недействительная регистрация, недопустимое название пакета, слишком большой размер сообщения, недопустимый ключ данных, недопустимое время жизни или другие недопустимые параметры. Недопустимая регистрация. Проверьте формат токена регистрации, который вы передаете на сервер. Убедитесь, что он совпадает с токеном регистрации, который клиентское приложение получает при регистрации в 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 Feedback Service сообщает, что токен APNs недействителен. - Если срок действия токена регистрации истек (например, Google может решить обновить токены регистрации или истек срок действия токена APN для iOS-устройств). - Если клиентское приложение обновлено, но новая версия не настроена на получение сообщений. Во всех этих случаях удалите токен регистрации с сервера приложений и прекратите использовать его для отправки сообщений. |
SENDER_ID_MISMATCH (код ошибки HTTP – 403). Идентификатор отправителя, прошедшего аутентификацию, не совпадает с идентификатором отправителя для токена регистрации. |
Токен регистрации связан с определенной группой отправителей. При регистрации клиентского приложения в FCM необходимо указать, каким отправителям разрешено отправлять сообщения. При отправке сообщений в клиентское приложение следует использовать один из этих идентификаторов отправителя. Если вы переключитесь на другой идентификатор, существующие токены регистрации перестанут работать. |
QUOTA_EXCEEDED (код ошибки HTTP – 429). Превышен лимит на отправку для целевого объекта сообщения. Возвращается расширение типа google.rpc.QuotaFailure, указывающее, какая квота была превышена. |
Эта ошибка может быть вызвана превышением квоты на частоту сообщений, частоту сообщений на устройстве или частоту сообщений по теме. Превышена частота отправки сообщений. Сообщения отправляются слишком часто. Вам необходимо снизить общую частоту отправки писем. Используйте экспоненциальную выдержку с минимальной начальной задержкой в 1 минуту, чтобы повторно отправлять отклоненные сообщения. Превышена частота отправки сообщений на устройство. Сообщения отправляются на определенное устройство слишком часто. Подробнее об ограничении частоты сообщений для одного устройства… Уменьшите количество сообщений, отправляемых на это устройство, и используйте экспоненциальную выдержку для повторной отправки. Превышена частота сообщений по теме. Частота сообщений подписчикам по определенной теме слишком высока. Уменьшите количество сообщений, отправляемых по этой теме, и используйте экспоненциальную выдержку с минимальной начальной задержкой в 1 минуту для повторной отправки. |
UNAVAILABLE (код ошибки HTTP – 503). Сервер перегружен. |
Сервер не смог обработать запрос вовремя. Повторите запрос, но при этом: - Учитывайте заголовок Retry-After, если он включен в ответ от сервера подключения FCM. - Реализуйте экспоненциальную выдержку в механизме повторных попыток. (например, если вы подождали одну секунду перед первой попыткой, подождите не менее двух секунд перед следующей, затем четыре секунды и т.д.). Если вы отправляете несколько сообщений, рекомендуем использовать джиттеринг. Дополнительную информацию вы найдете в разделе обработки повторных попыток.Вы также можете проверить панель мониторинга FCM, чтобы узнать, не возникли ли в работе сервиса сбои, которые могут повлиять на FCM. Отправители, которые вызывают проблемы, рискуют попасть в черный список. |
INTERNAL (код ошибки HTTP – 500). Произошла неизвестная внутренняя ошибка. |
При обработке запроса произошла ошибка сервера. Вы можете повторить запрос, следуя рекомендациям из раздела Повторные попытки , или проверить панель мониторинга FCM. чтобы узнать, есть ли сбои в работе FCM. Если ошибка не исчезнет, обратитесь в службу поддержки Firebase. |
THIRD_PARTY_AUTH_ERROR (код ошибки HTTP – 401). Сертификат APNs или ключ аутентификации веб-пуш-уведомлений недействителен или отсутствует. |
Не удалось отправить сообщение, предназначенное для 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 |
Указанный токен регистрации не зарегистрирован. Регистрация токена, который ранее был действительным, может быть отменена по разным причинам, в том числе:
|
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 не смог обработать запрос вовремя. Повторите запрос, но:
|
messaging/internal-error |
При обработке запроса на сервере FCM произошла ошибка. Вы можете повторить запрос, следуя требованиям, указанным в строке messaging/server-unavailable. Если ошибка не исчезнет, сообщите о ней через отчет об ошибке канал поддержки.
|
messaging/unknown-error |
Возвращена неизвестная ошибка сервера. Подробные сведения можно найти в необработанном ответе сервера в сообщении об ошибке. Если вы получили такое сообщение об ошибке, отправьте его полный текст в службу поддержки через форму сообщения об ошибке. |