FCM 404 "Requested entity was not found" errorCode: "UNREGISTERED"

Question

I am using WebPush in my project and it works well for the most part. However, occasionally - often after a prolonged period of use - a user will receive a 404 error with the following JSON response:

{
  "error": {
    "code": 404,
    "message": "Requested entity was not found.",
    "status": "NOT_FOUND",
    "details": [
      {
        "@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
        "errorCode": "UNREGISTERED"
      }
    ]
  }
}

What appears to be happening is that the token is expiring. The function onTokenRefresh() is cited on numerous occasions, but with little documentation on how to implement and certainly none regarding how to test. Some users have reported clearing cache will force a token refresh; this is not the case for me.

I have had this problem for nearly 6 months, and regularly check back to see if the documentation has improved, but there is no clear solution to this problem.

Any solutions to test at this point would be enormously appreciated. I am sure there are others out there using the under-documented WebPush notifications with similar issues.

Solution

onTokenRefresh() (now deprecated. Use onNewToken(String s) implementing FirebaseMessagingService, check out this other answer FirebaseInstanceIdService is deprecated) is called every time the application installed gets a new token, whatever the reason it is (for instance, if the user goes to the "Applications" android configuration menu option, selects your application and press "Clear Data", but that is just one reason).

You have to use this method to call your backend and update the places where you stored the previous token, in order for your backend not to use it anymore to send any messages to it as it had been expired (and thus throwing the NOT_FOUND/UNREGISTERED error).

Don't forget to add the following in your AndroidManifest.xml as stated in the documentation:

Include the following in the manifest:

<service android:name=".YourFirebaseMessagingService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
   </intent-filter>

Documentation of the new FirebaseMessagingService:

https://firebase.google.com/docs/reference/android/com/google/firebase/messaging/FirebaseMessagingService