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 CodeDescription
UNSPECIFIED_ERRORNo 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:
  1. Invalid registration: Ensure the registration token's format matches what the client app receives from FCM.
  2. Invalid package name: Verify the message was addressed to a registration token with a matching package name.
  3. Message too big: Ensure the payload data size is within FCM limits (4096 bytes for most messages, 2048 bytes for topic messages).
  4. Invalid data key: Ensure payload data does not contain reserved keys (e.g., from, gcm, or any prefixed by google).
  5. Invalid TTL: Confirm ttl value is an integer between 0 and 2,419,200 seconds (4 weeks).
  6. 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:
  1. Missing Registration: Ensure the request contains a registration token.
  2. 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:
  1. Message rate exceeded: Reduce overall message-sending rate; use exponential backoff starting at 1 minute.
  2. Device message rate exceeded: Reduce messages to a single device; use exponential backoff.
  3. 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

Invalid RegistrationIf 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.
MismatchSenderIdThe 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 JSONEnsure that the JSON message is correctly structured and includes valid fields within the Name-Value pairs you're transmitting.
Message Too BigEnsure 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.
INTERNALThe 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 ExceededThe frequency of messages sent to a specific user is excessive.
NoneThis 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
Processing errorThere was a problem on APNS's end.
OthersThere was a problem on APNS's end.
Invalid tokenIt appears that the users' tokens have expired.
Invalid payload sizeMake 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.
BadCollapseIdThe collapse identifier surpasses the maximum permitted size.
BadDeviceTokenThe token shared with Netcore Cloud was incorrect or invalid. Ensure that the request contains a valid token that matches the environment.
BadMessageIdThe specified value for "apns-id" is incorrect.
BadPriorityThe specified value for "apns-priority" is incorrect.
DeviceTokenNotForTopicThe device token doesn't correspond to the specified topic.
DuplicateHeadersSome headers were duplicated in the request.
MissingDeviceTokenThis 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.
MissingTopicThis 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.
BadCertificateThis error usually arises when the certificate used for authentication during the push notification process is corrupted or not valid.
UnregisteredThis message indicates that the device token is no longer active. This typically happens when app has been installed from the device.
InternalServerErrorAn 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.