Error Codes for Mobile Push Notifications

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.

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.

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:

1. Firebase registration error — permission was granted, but Firebase didn't return a token due to a network error during registration; retry usually resolves this.
2. 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 Reteno 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.

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.

A mobile push with a linked In-App has no separate In-App statuses: a tap on the push itself adds no status, and a click on an In-App button is counted for the push as READ and CLICKED.

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

Troubleshooting: Pending Status

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

On the Contact Activity tab, in the Campaigns category, the same state is shown as Unknown: the delivery service accepted the push without an error, but the app didn't send a delivery status. The Unknown status doesn't remove the token — only an error during sending does.

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 recent their app activity events are — for example, the ApplicationOpened event.

Troubleshooting: Delivered Status Isn't Registered on iOS

On iOS, the delivered status of a push notification received while the app is closed is registered only if the app includes a Notification Service Extension — see iOS SDK Setup. Without the extension, the status is reported only while the app is active.

For server-to-server integrations without the Reteno SDK, delivery statuses are reported by the app itself. To track delivery while the app is closed, implement the same logic in a Notification Service Extension in your app.