Admin FCM API Errors

Here is a full list of the error codes and descriptions, including recommended resolution steps, that are thrown by the Firebase Admin Node.js FCM API:

Error Code Description and Resolution Steps
messaging/invalid-argument An invalid argument was provided to an FCM method. The error message should contain additional information.
messaging/invalid-recipient The intended message recipient is invalid. The error message should contain additional information. See Send Messages for documentation on how to properly send messages to a variety of recipient types.
messaging/invalid-payload An invalid message payload object was provided. The error message should contain additional information. See Defining the message payload for documentation on how to properly define the message payload.
messaging/invalid-data-payload-key The data message payload contains an invalid key. See the reference documentation for DataMessagePayload for restricted keys.
messaging/payload-size-limit-exceeded The provided message payload exceeds the FCM size limits. The limit is 4096 bytes for most messages. For messages sent to topics and notification messages sent to iOS devices, the limit is 2048 bytes. The total payload size includes both keys and values.
messaging/invalid-options An invalid message options object was provided. The error message should contain additional information. See Defining the message options for details on how to properly define the message options.
messaging/invalid-registration-token Invalid registration token provided. Make sure it matches the registration token the client app receives from registering with FCM. Do not truncate or add additional characters to it.
messaging/registration-token-not-registered The provided registration token is not registered. A previously valid registration token can be unregistered for a variety of reasons, including:
  • The client app unregistered itself from FCM.
  • The client app was automatically unregistered. This can happen if the user uninstalls the application or, on iOS, if the APNS Feedback Service reported the APNS token as invalid.
  • The registration token expired. For example, Google might decide to refresh registration tokens or the APNS token may have expired for iOS devices.
  • The client app was updated, but the new version is not configured to receive messages.
For all these cases, remove this registration token and stop using it to send messages.
messaging/invalid-package-name The message was addressed to a registration token whose package name does not match the provided restrictedPackageName option.
messaging/device-message-rate-exceeded The rate of messages to a particular device is too high. Reduce the number of messages sent to this device and do not immediately retry sending to this device.
messaging/topics-message-rate-exceeded The rate of messages to subscribers to a particular topic is too high. Reduce the number of messages sent for this topic, and do not immediately retry sending to this topic.
messaging/too-many-topics A registration token has been subscribed to the maximum number of topics and cannot be subscribed to any more.
messaging/invalid-apns-credentials A message targeted to an iOS device could not be sent because the required APNs SSL certificate was not uploaded or has expired. Check the validity of your development and production certificates.
messaging/mismatched-credential The credential used to authenticate this SDK does not have permission to send messages to the device corresponding to the provided registration token. Make sure the credential and registration token both belong to the same Firebase project. See Add Firebase to your app for documentation on how to authenticate the Admin SDKs.
messaging/authentication-error The SDK could not authenticate to the FCM servers. Make sure you authenticate the Admin SDK with a credential which has the proper permissions to send FCM messages. See Add Firebase to your app for documentation on how to authenticate the Admin SDKs.
messaging/server-unavailable The FCM server could not process the request in time. You should retry the same request, but you must:
  • Honor the Retry-After header if it is included in the response from the FCM Connection Server.
  • Implement exponential back-off in your retry mechanism. For example, if you waited one second before the first retry, wait at least two seconds before the next one, then four seconds, and so on. If you're sending multiple messages, delay each one independently by an additional random amount to avoid issuing a new request for all messages at the same time.
Senders that cause problems risk being blacklisted.
messaging/internal-error The FCM server encountered an error while trying to process the request. You could retry the same request following the requirements listed in the messaging/server-unavailable row above. If the error persists, please report the problem to our Bug Report support channel.
messaging/unknown-error An unknown server error was returned. See the raw server response in the error message for more details. If you receive this error, please report the full error message to our Bug Report support channel.

Send feedback about...

Need help? Visit our support page.