Коды ошибок 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 содержит информацию, которая поможет вам выполнить отладку и устранить проблему.
В таблице ниже перечислены коды ошибок REST API FCM версии 1 и их описания.
| Код ошибки | Описание и инструкции по устранению неполадок |
|---|---|
UNSPECIFIED_ERROR Дополнительная информация об этой ошибке недоступна. |
Нет. |
INVALID_ARGUMENT (код ошибки HTTP = 400). Недопустимые параметры запроса. Возвращается расширение типа google.rpc.BadRequest, чтобы указать, какое поле было недействительным. |
Возможные причины: недействительная регистрация, недействительное название пакета, слишком большой размер сообщения, недействительный ключ данных, недействительное время жизни или другие недействительные параметры. Недействительная регистрация. Проверьте формат токена регистрации, который вы передаете на сервер. Он должен совпадать с токеном регистрации, который клиентское приложение получает при регистрации в FCM. Не обрезайте токен и не добавляйте в него дополнительные символы. Недопустимое название пакета. Убедитесь, что сообщение было адресовано регистрационному токену, название пакета которого совпадает со значением, переданным в запросе. Слишком большое сообщение. Убедитесь, что общий размер данных полезной нагрузки, включенных в сообщение, не превышает ограничений FCM: 4096 байт для большинства сообщений или 2048 байт для сообщений, отправляемых в темы. включая ключи и значения. Недопустимый ключ данных. Убедитесь, что полезная нагрузка не содержит ключ (например, from, gcm или любое значение с префиксом google), который используется FCM внутри системы. Обратите внимание, что некоторые слова (например, collapse_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, чтобы указать, какая квота была превышена. |
Эта ошибка может быть вызвана превышением квоты на частоту отправки сообщений, квоты на частоту отправки сообщений устройством или квоты на частоту отправки сообщений в тему. Превышена частота отправки сообщений. Частота отправки сообщений слишком высокая. Вам необходимо снизить общую скорость отправки писем. Используйте экспоненциальную выдержку с минимальной начальной задержкой в одну минуту, чтобы повторно отправлять отклоненные сообщения. Превышена частота сообщений на устройство – частота отправки сообщений на определенное устройство слишком высока. Подробнее об ограничении скорости передачи сообщений на одно устройство… Уменьшите количество сообщений, отправляемых на это устройство, и используйте экспоненциальную выдержку для повторной отправки. Превышена частота сообщений в теме – частота отправки сообщений подписчикам определенной темы слишком высока. Уменьшите количество сообщений, отправляемых по этой теме, и используйте экспоненциальную выдержку с минимальной начальной задержкой в одну минуту, чтобы повторить отправку. |
UNAVAILABLE (код ошибки HTTP = 503). Сервер перегружен. |
Сервер не смог обработать запрос вовремя. Повторите тот же запрос, но при этом: – учитывайте заголовок Retry-After, если он включен в ответ от сервера подключения 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 |
Указанный токен регистрации не зарегистрирован. Ранее действительный токен регистрации может быть отменен по разным причинам, в том числе:
|
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 |
Возникла неизвестная ошибка сервера. Подробную информацию можно найти в сообщении об ошибке, в котором приведен необработанный ответ сервера. Если вы получили такое сообщение об ошибке, отправьте его полный текст в отчет об ошибке. |