Common push error messages

Error sending push because the payload was invalid

This message can appear in the user profile Engagement tab under Contact Settings > Push Changelog when Apple Push Notification service (APNs) rejects the push request because of an invalid payload.

In Braze, this dashboard message can map to one of the following APNs error reasons:

• PayloadEmpty: The payload was missing required content for the type of push being sent.
• PayloadTooLarge: The payload exceeded APNs’ maximum payload size.

Common causes include:

• Custom keys (and their values) making the payload too large (this can include unexpectedly large Liquid-rendered values).
• An empty or missing alert or body where required (or an otherwise malformed aps payload).

Next steps:

• Reduce payload size by trimming custom keys and shortening large dynamic values.
• If you send through the API, validate the final JSON payload (including size) before sending.

Push bounced: BadToken

The BadToken error may occur for several reasons:

• The push token isn’t being sent to Braze correctly (for example, in registerDeviceToken: or your platform’s equivalent).
  • Check the token in the Message Activity Log. It should generally look like a long string of letters and numbers (such as 6e407a9be8d07f0cdeb9e714733a89445f57a89ec890d63867c482a483506fa6). If it doesn’t, check the code involved in sending Braze the push token.
    
    
• Mismatched provisioning environment:
  • If you register with a development certificate and try to send with a production one, you can see this error.
  • Braze only supports universal certificates for production environments. Testing push on development environments with a universal certificate will not work.
  • This reporting sends bouncing in production but not development.
    
    
• Mismatched provisioning profile:
  • This can happen if your certificate doesn’t match the one that was used to get the token. If this is suspected, the next steps include:
    • Ensuring that the push certificate being used to send push from the Braze dashboard and the provisioning profile are configured correctly.
    • Recreating the APNS certification and then recreate the provisioning profile after the APNS certificate is configured to the app_id. This can sometimes solve some more visible problems.

Bundle ID not allowed

The TopicDisallowed error means APNs rejected the push because the topic (bundle ID) in the request isn’t allowed for the authentication credentials being used. To resolve this:

1. Verify the bundle ID. Confirm the bundle ID configured in your Braze app settings matches the bundle ID of your app exactly. This includes any suffix variations (for example, .debug, .staging).
2. Check your APNs authentication setup. Confirm your app is configured with the correct APNs .p8 key and that the key is associated with the same Apple Developer Team as the app you’re sending to.
3. Confirm the app environment. If you have separate App IDs in Braze for development and production builds, verify that each is configured with the correct push credentials and environment.

Unregistered

This error appears in the Message Activity Log as:

Received 'Unregistered' sending to '[Token String]'

This is the iOS equivalent of the Android DEVICE_UNREGISTERED error. It typically occurs for one of the following reasons:

• The user uninstalled the app. This is the most common cause.
• Push certificates were updated. If your team changed or renewed the APNs certificates, users who registered with the previous certificates may have invalid tokens until the app re-registers them.
• Custom logic is unregistering users from push. This is rare, but it’s technically possible to programmatically unregister from remote notifications using the iOS SDK.

InvalidProviderToken

The InvalidProviderToken error means APNs rejected the request because the authentication token (from a .p8 key) or the push certificate (.p12) doesn’t match the app’s bundle ID or Team ID. To resolve this:

1. Verify your Team ID and Key ID: If you’re using a .p8 authentication key, confirm that the Team ID and Key ID configured in the Braze dashboard (Settings > App Settings > select your iOS app) match the values in your Apple Developer account.
2. Check the bundle ID: Make sure the bundle ID registered in Braze matches the bundle ID of your app. A mismatch, such as a different capitalization or a .debug suffix, causes this error.
3. Re-upload the key or certificate: If the .p8 key or .p12 certificate was recently regenerated or revoked, upload the new key to Braze and remove the old one.
4. Confirm the APNs environment: If you’re using a .p12 certificate, verify you selected the correct environment (development versus production) when uploading it. For .p8 keys, this is handled automatically.

Push bounced: APNS feedback service removed

This generally happens when someone uninstalls. Braze queries the APNS Feedback Service each night to get a list of invalid tokens. For more information, refer to Apple’s Communicating with APNs.