Google Health API errors: the v4 error catalog and troubleshooting

A user must sign in to the Google Health mobile app to link Google Health to their Google Account before your app can sync data through the Google Health API. See Link Google Health before OAuth consent. Because Google OAuth 2.0 authenticates any valid Google Account during consent, it cannot block accounts that don't yet have an active Google Health profile.

If a user completes Google OAuth consent before creating a Google Health profile or before migrating their legacy Fitbit account to their Google Account, calling users.getIdentity or a data endpoint returns an HTTP 400 Bad Request error with status FAILED_PRECONDITION and reason ACCOUNT_NOT_LINKED:

{
  "error": {
    "code": 400,
    "message": "The account is not linked to Google Health.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCOUNT_NOT_LINKED",
        "domain": "health.googleapis.com",
        "metadata": {
          "redirect_uri": "https://fitbit.google.com/auth/signup"
        }
      }
    ]
  }
}

To verify account access and handle this error:

1. Exchange the OAuth authorization code for tokens and immediately call users.getIdentity (GET https://health.googleapis.com/v4/users/me/identity) before marking the account as linked in your app UI.
2. If users.getIdentity or a background data sync call returns HTTP 400 with reason ACCOUNT_NOT_LINKED, don't mark the account as connected. If the user is migrating from the legacy Fitbit Web API, keep their existing Fitbit connection active and don't revoke their legacy Fitbit tokens.
3. Display an actionable prompt that addresses both new users who have never created a Google Health or Fitbit account and existing Fitbit users who have not yet migrated to a Google Account:
   "Your Google Account isn't linked to Google Health yet. Open the Google Health mobile app and sign in with your Google Account to create a profile, or move your existing Fitbit account to your Google Account, then return here to connect."
4. Provide a call-to-action button that opens the redirect_uri from the error metadata (https://fitbit.google.com/auth/signup) or direct legacy Fitbit users to the Fitbit account migration help article.

To help troubleshoot a user issue, you may need to verify the Google Account of the user logged into the Google Health app.

To find the legacy Fitbit user ID:

1. Open the Google Health app.
2. Press the Health icon in the bottom right hand corner.
3. In the "Personal info" section, press Profile.
4. In the "Account information" section, the value assigned to the ID is the legacy Fitbit user ID. (For example: CV5TKH)

When helping a user troubleshoot their OAuth2 connection to your app, you may need them to unlink their account from your app and then complete your authorization flow again.

To unlink their Google Account from your app:

1. Open the Google Health app.
2. Press the user profile icon in the upper right corner.
3. Press Apps and services.
4. Look for your app name in the list of connected apps, and have the user select it.
5. For legacy Fitbit API applications, the "Connected apps" page will appear. Have the user press disconnect under the app name.
6. For all other apps, the "Linked apps" page will appear. Have the user find the Google Health API app and select it. Press "Delete all". Have the user press confirm to revoke consent to your app.

When the revoke process completes, the user will be taken back to the list of Third-party apps & services page. The user might need to refresh the page to see the app name removed from the list.

When debugging issues related to missing or delayed user data, it is helpful to check the user's paired device model and their last synchronization date.

The model information (such as a Fitbit tracker or smartwatch model) and last sync date are useful for troubleshooting and to fetch historical data after syncing delays.

For example, if you notice an unexpected gap or delay in data delivery:

1. Verify that the user ID you are querying matches the user ID of the Fitbit account logged into the mobile app. To obtain the user ID in the mobile app, see Retrieve a Fitbit user ID. To obtain the user ID from the access token, call the getIdentity endpoint.
2. Check the last sync time to determine when the user's device last synced with the Google Health mobile app.
3. If the device has not synced recently, it indicates that the delay is likely due to the device being offline or not syncing with the mobile application, rather than an API issue.
4. Once the user opens the mobile application and syncs their device, you can fetch historical data for the period since the last sync time.

To retrieve a user's paired device information, call the users.pairedDevices.list endpoint. This returns a list of devices containing:

• deviceVersion: The product name or model of the device (for example, "Charge 6").
• lastSyncTime: The timestamp of the last successful synchronization.