FCM Error Code Reference

Cause: The device/web-push token is no longer valid — the app was uninstalled, the token expired, or the browser subscription was revoked.

Fix: Remove the token from your database and stop sending to it. Have the client re-register and store the new token.

Cause: The message payload is malformed — an invalid field, a value of the wrong type, or a token that isn't correctly formatted.

Fix: Check every field against the FCM message schema. Test the exact payload with the WEB_PUSH tab's validate-only dry run before sending for real.

Cause: The token was generated by a different Firebase project than the service account you're sending with.

Fix: Confirm the token's client app is registered under the same Firebase project as the service account JSON you uploaded.

Cause: For iOS (APNs) delivery: the APNs certificate or authentication key configured in Firebase is invalid, expired, or missing.

Fix: Regenerate and re-upload the APNs auth key or certificate in the Firebase console under Project Settings → Cloud Messaging.

Cause: You're sending messages faster than FCM's rate limits for your project or token.

Fix: Back off and retry with exponential backoff. If this happens at low volume, check for a send loop in your own code.

Cause: FCM's servers returned a transient error — usually temporary infrastructure load.

Fix: Retry with exponential backoff. This is not caused by your payload or credentials.

Cause: An unexpected error occurred on FCM's side while processing the request.

Fix: Retry the request. If it persists across retries, check the Firebase status dashboard for an ongoing incident.

Cause: The service account used to authenticate doesn't have permission to send to the token's project.

Fix: Verify the service account JSON belongs to the same Firebase project as the target app/token.

Cause: The token, topic, or condition provided as the message target is malformed.

Fix: Double check you're pasting a full device/registration token, not a truncated value or a project ID.

Cause: The service account JSON is invalid, revoked, or the private key doesn't match Firebase's records.

Fix: Generate a fresh service account key from Project Settings → Service Accounts → Generate new private key, then re-upload.