Error Codes for App Push Notifications

Netcore utilizes Firebase Cloud Messaging (FCM) for Android notifications and Apple Push Notification Service (APNS) for iOS notifications. Notifications may run into certain failures during submission to FCM or APNS; such errors are logged as Failures at Netcore. The most common reasons are listed below:

Android-Firebase Cloud Messaging Errors

FCM HTTP V1 Error Codes

Refer to the error code below for users who have migrated to FCM HTTP v1.

Error Code	Description
UNSPECIFIED_ERROR	No information is available for this error.
INVALID_ARGUMENT (HTTP error code = 400)	Request parameters were invalid. An extension of type `google.rpc.BadRequest` specifies which field was invalid. Potential causes include: Invalid registration: Ensure the registration token's format matches what the client app receives from FCM. Invalid package name: Verify the message was addressed to a registration token with a matching package name. Message too big: Ensure the payload data size is within FCM limits (4096 bytes for most messages, 2048 bytes for topic messages). Invalid data key: Ensure payload data does not contain reserved keys (e.g., from, gcm, or any prefixed by google). Invalid TTL: Confirm ttl value is an integer between 0 and 2,419,200 seconds (4 weeks). Invalid parameters: Ensure parameters have correct names and types.
UNREGISTERED (HTTP error code = 404)	The app instance was unregistered from FCM, which usually indicates that the token used is no longer valid. This error can be caused by: Missing Registration: Ensure the request contains a registration token. Not Registered: The token may be invalid due to the client app unregistering with FCM or the user uninstalling the app (e.g., APNs token invalidation on iOS) or token expiration. The app update is not configured to receive messages. Remove the invalid token from the app server and stop using it.
SENDER_ID_MISMATCH (HTTP error code = 403)	The authenticated sender ID differs from the registration token's sender ID. Use the correct sender ID that matches the registration tokens when sending messages.
QUOTA_EXCEEDED (HTTP error code = 429)	Sending limit exceeded for the message target `. google.rpc.QuotaFailure` specifies which quota was exceeded. Reduce the message-sending rate: Message rate exceeded: Reduce overall message-sending rate; use exponential backoff starting at 1 minute. Device message rate exceeded: Reduce messages to a single device; use exponential backoff. Topic message rate exceeded: Reduce messages to a topic; use exponential backoff.
UNAVAILABLE (HTTP error code = 503)	The server is overloaded and couldn't process the request in time. Retry the request, honoring the Retry-After header if included, and implement exponential back-off (e.g., wait 1 second, then 2 seconds, then 4 seconds, etc.). Apply jittering if sending multiple messages to avoid being denylisted.
INTERNAL (HTTP error code = 500)	An unknown internal error occurred. Retry the request following the handling retries guidelines. If the error persists, contact Firebase support.
THIRD_PARTY_AUTH_ERROR (HTTP error code = 401)	APNs certificate or web push auth key was invalid or missing. Verify the validity of development and production credentials for iOS device or web push registration.

Legacy FCM Server Key Error Codes

Error	Description
Invalid Registration	If you're managing FCM independently, there's a chance you've submitted an incorrect token.
UNREGISTERED (HTTP error code = 404)	App instance was unregistered from FCM. This usually means that the token used is no longer valid and a new one must be used. An existing registration token may cease to be valid in a number of scenarios, including: - If the client app unregisters with FCM. - If the client app is automatically unregistered, which can happen if the user uninstalls the application. - If the registration token expires (for example, Google might decide to refresh registration tokens). - If the client app is updated but the new version is not configured to receive app push messages.
MismatchSenderId	The authenticated sender ID is different from the sender ID for the registration token. To resolve this, update the Android Server Key stored in Netcore Cloud. You can do this by going to App Assets section in settings and update the respective android app asset settings.
Invalid JSON	Ensure that the JSON message is correctly structured and includes valid fields within the Name-Value pairs you're transmitting.
Message Too Big	Ensure that the total size of the payload data in your message doesn't surpass the GCM limit of 4096 bytes. Consider reducing the number of Name-Value pairs you're passing if needed to stay within this limit.
INTERNAL	The server encountered an error while trying to process the request. You could retry the same request following the requirements listed in "Timeout" (see row above)
Device Message Rate Exceeded	The frequency of messages sent to a specific user is excessive.
None	This is an UNSPECIFIED_ERROR with no information available from FCM

Refer to the Firebase: Error Code Documentation for more information.

iOS - Apple Push Notification Service Errors

Error	Description
Processing error	There was a problem on APNS's end.
Others	There was a problem on APNS's end.
Invalid token	It appears that the users' tokens have expired.
Invalid payload size	Make sure the combined size of the payload data within a message doesn't exceed APNS limits, typically set at 4096 bytes. You might need to reduce the number of key-value pairs you're including to stay within this limit.
BadCollapseId	The collapse identifier surpasses the maximum permitted size.
BadDeviceToken	The token shared with Netcore Cloud was incorrect or invalid. Ensure that the request contains a valid token that matches the environment.
BadMessageId	The specified value for "apns-id" is incorrect.
BadPriority	The specified value for "apns-priority" is incorrect.
DeviceTokenNotForTopic	The device token doesn't correspond to the specified topic.
DuplicateHeaders	Some headers were duplicated in the request.
MissingDeviceToken	This message typically refers to a missing device token within the request path. It's crucial to ensure that the designated path header contains the necessary device token for the intended operation to be carried out successfully.
MissingTopic	This error suggests that the request lacks the essential "apns-topic" header. When a client connects using a certificate that supports multiple topics, providing this header becomes mandatory. It ensures that the request is properly identified and processed within the APNS system.
BadCertificate	This error usually arises when the certificate used for authentication during the push notification process is corrupted or not valid.
Unregistered	This message indicates that the device token is no longer active. This typically happens when app has been installed from the device.
InternalServerError	An internal server error indicates that something went wrong on the server's end while attempting to fulfill a request.

Refer to the Firebase: Error Code documentation for more details.