Error Codes for Mob Push Notifications

Read this article in Ukrainian ⮕

In mobile application development, errors and issues are inevitable, especially when dealing with complex services like Firebase and APNS.

This article provides a comprehensive guide to understanding common error scenarios, their causes, and actionable solutions.

Unlike mobile push, email doesn't have a unified list of error codes documented here — the exact error text varies by receiving mail provider, so email delivery errors are best checked directly in campaign reports rather than matched against a fixed code table.

This structured error-code table applies to mobile push. There isn't an equivalent unified list of error codes for email — the exact error text and codes vary by receiving mail provider, so check the specific error message returned for that delivery.

Error	Possible Cause	Troubleshooting
Device token not registered	When using Firebase for iOS and Android, APN certificates added to Firebase may expire or not be generated for the required environment. When adding an Apple application to an FCM project, ensure that certificates are uploaded separately for each environment. It is possible that the production certificate is being used for the development environment, or vice versa.	Check the certificate's validity and if it is used in the proper environment.
The authenticated sender ID is different from the sender ID for the registration token	A problem with the Firebase service account.	Try to expand permissions in the service account.
	The token was generated in one Firebase project, but the push attempt was made from another. It is possible that a token from the test environment is being used in production, or vice versa.	Ensure the proper use of tokens.
`MOB_PUSH_GENERAL_ERROR`	The error has no description from the APNS service and may indicate a failure on the APNS service side.	Contact our support team for a detailed analysis.
No more information is available about this error	No information about the error.	Contact our support team for a detailed analysis.
Request parameters were invalid	APNS was selected for push notifications in the admin panel, but the SDK is set up to use FCM tokens, or vice versa.	Solution Options: Adjust the settings in the admin panel. Or, ensure the SDK transmits tokens that correspond to those selected in the admin panel.
`InvalidProviderToken`	The APN authentication token used for sending notifications via APN might have been revoked in the Apple Developer Center.	Create a new APNs Auth Key.
	Incorrect setup of the p8 certificate.	Check the certificate settings.
`badDeviceToken`	The error occurs when an APNs token issued for the sandbox environment is used in production, or vice versa. A build signed with a development certificate gets a sandbox token.	Test push notifications on a TestFlight or App Store build — its token belongs to the production environment.
Invalid registration token/The registration token is not a valid FCM	The application is configured via FCM, but the contact has an APN token, and vice versa. When receiving such an error, the token is automatically deleted.	Configure FCM/APN.
`TopicDisallowed`	This error can occur when using APNs tokens when the Bundle Identifier in the eSputnik push settings (associated with the `AuthKey .p8` file) does not match the app's Bundle Identifier where the push notification is being tested.	Compare the value specified in the Topic field when creating the app in the eSputnik admin panel with the Bundle Identifier of the app where the push notification is being tested.

Troubleshooting: Sandbox and Production Environments on iOS

BadEnvironmentKeyInToken and badDeviceToken mean the same thing: the token and the environment don't match.

One APNs Auth Key covers both environments, but the environments stay separate: a token issued to a debug build works only in sandbox, and a token issued to a TestFlight or App Store build works only in production. The key alone does not make both work at once.

Tokens from debug builds can therefore return these errors. To test pushes, use a TestFlight or App Store build.

Statuses Returned by the API

For the mobile push channel, Get single message status returns one of the following statuses: ERROR, DELIVERED, READ, CLICKED, EXPIRED, IN_QUEUE, PENDING. The READ status doesn't come from the device: the SDK can't reliably detect that a notification was read, so the system derives READ from a registered click.

The reason for a specific failed send comes in the statusDescription field — in webhooks and in the BigQuery export.

The Pending Status

The Pending (In progress) status means that neither a delivery status nor an error has been received after the message was sent. A typical cause is that the app has been uninstalled, or notifications are disabled and the app hasn't been opened since: the contact's token remains in the system, but no statuses arrive for it.

Occasional cases like this are normal. If a large share of contacts stays in the Pending status across several campaigns in a row, it indicates an error in the app integration setup, or that many users declined notifications or deleted the app.

To diagnose such contacts, check how long ago their latest activity events (for example, ApplicationOpened) occurred.

When a Push Token Is Reissued

A mobile push token isn't reissued on every app launch and isn't tied to the user's authorization. A new token is generated when the app is launched for the first time after installation, when the app is reinstalled, when the previous token is invalidated, or when the app deletes the token in code. In all other cases the SDK reuses the existing token.

On iOS, after the app is reinstalled, the SDK gets a new Device ID unless other apps from the same developer remain on the device; if they do, the Device ID stays the same. The SDK can't detect that the app was deleted, so when the user logs in, another device with a new token appears in the contact. The previous token isn't removed at that point: it's removed only when a send to it returns an error.

On iOS, the token can change several times a day if the SDK's token handling mode doesn't match how the app passes the token. In .automatic mode, the SDK picks up the APNs token on its own, so if the app also passes an FCM token, the contact's token is overwritten by one and then the other, and sends fail with an error. To choose the mode, see step 2 of the iOS SDK setup.

Troubleshooting: Device Registered Without Push Token

Sometimes the SDK successfully registers a deviceID for a contact, but no push token is attached, even though the user has granted notification permissions. Check the following:

Firebase registration error — permission was granted, but Firebase didn't return a token due to a network error during registration; retry usually resolves this.
Missing push entitlement in the provisioning profile (iOS) — the app's provisioning profile must include the push notification entitlement, or APNs won't issue a token.

📘
Push tokens: registration and removal
It's normal for the SDK to send several registration requests in a row during initialization (for example, first with only the deviceID, then a later request with the push token once it becomes available).
"Device token not registered" is a delivery-time error, and the system automatically removes the token when it occurs. This doesn't necessarily mean the app was uninstalled — the token can become invalid for other reasons. A removed token cannot become valid again: when the user subscribes to push notifications again, a new token is registered. There's no segment filter that isolates contacts affected by this cause alone from other token-removal reasons.
There is no background or scheduled token cleanup without a send attempt — a token is removed only when a delivery attempt returns such an error, so an unused invalid token remains in the account until the next send to it.