Every question the Troubleshooting pages answer

The 25 troubleshooting pages answer 103 named questions between them. Every one is listed below, and every link lands on the paragraph that answers it rather than the top of the page.

Why Is My Fitness API Returning 401 Unauthorized?

What is the difference between a 401 and a 403 from a fitness API?A 401 Unauthorized means authentication failed: the token is missing, malformed, expired, revoked, or the wrong type. A 403 Forbidden means…
Will refreshing my token fix a 401?Usually yes, if the cause is an expired access token, which is the most common reason for a sudden 401. Refresh the token and retry. It…
Why does my Authorization header cause a 401 even with a valid token?The header must be exactly the word Bearer, a space, then the access token (for example, Authorization: Bearer eyJhbGci...). Common…
How do I know which specific cause triggered my 401?Read the WWW-Authenticate response header, which spec-compliant servers use to report an error like invalid_token, plus the JSON body.…
My refresh worked once and now returns invalid_grant — is that a 401 problem?No, that is a refresh-token rotation problem. Providers such as Strava, WHOOP, Oura, and Garmin return a new refresh token on refresh and…

How to Fix the OAuth redirect_uri Mismatch Error

Why do localhost and 127.0.0.1 count as a mismatch?OAuth servers compare the redirect_uri as an exact string, not by what it resolves to. localhost and 127.0.0.1 are different strings even…
Does a trailing slash really matter?Yes. /callback and /callback/ are different strings to the matcher, so one will fail if the other is registered. Frameworks and proxies…
Why do I get invalid_grant instead of redirect_uri_mismatch?A redirect mismatch caught at the authorize step reads as redirect_uri_mismatch, but the same mismatch caught at the token step can read as…
Do the authorize and token steps need the same redirect_uri?Yes. The redirect_uri sent when you build the authorize URL and the one sent when you exchange the code must be the identical string. If…
How do I support local, staging, and production callbacks?Register each environment's exact callback URL separately in the developer console, for example an http localhost URL for dev and https…

Why Is My Fitness API Refresh Token Not Working?

Why does my refresh token work the first time but fail after that?Because the provider rotated it. Strava, WHOOP, Oura, Garmin, and Fitbit return a new refresh token in the refresh response and invalidate…
What does invalid_grant mean on the token endpoint?It is an overloaded OAuth 2.0 error meaning the grant you sent is invalid, expired, revoked, or does not match. For refreshes it usually…
Do I need to save the refresh token even when it looks unchanged?Yes. Providers that usually return the same token can still rotate without warning. The safe rule is to always overwrite your stored…
My refresh keeps failing but I am saving the token. What else could it be?Check for concurrent refreshes on the same user, which race and invalidate each other, and verify your server clock is NTP-synced. If the…
Why did I never receive a refresh token at all?You probably did not request the scope that grants offline access. WHOOP requires the offline scope, and other providers need…

How to Fix Fitbit API 429 (Rate Limit) Errors

What is the Fitbit API rate limit?As of 2026, Fitbit allows roughly 150 requests per hour per consented user, resetting near the top of each hour (verify against current…
Is the Fitbit rate limit per app or per user?It is counted per consented user, not per application. That means a single bad loop or aggressive polling job on one user's data can…
How do I know when I can retry after a Fitbit 429?Read the Fitbit-Rate-Limit-Reset header, which gives the number of seconds until the window resets, or the Retry-After header when present.…
How do I stop hitting the Fitbit rate limit?Cache data that does not change, reduce and batch calls, stagger background syncs so users are not all refreshed at once, and replace…
Is the Fitbit API being deprecated or migrated?Fitbit's developer platform is moving toward Google's Health ecosystem, with the Fitbit Web API being consolidated into Google Health APIs…

Why Is HealthKit Returning No Data?

Can I detect whether the user denied read access in HealthKit?No. Apple deliberately hides read-authorization state to avoid leaking that health data exists, so authorizationStatus(for:) only reports…
Why does authorizationStatus(for:) say authorized but my read is still empty?That status reflects write/share permission, not read. The user can allow writing while blocking reading, and HealthKit will not tell you.…
Does HealthKit work on the iOS Simulator?Partly, but the Simulator has little or no Health data and inconsistent behavior, so queries often return empty even with correct code.…
My app crashes when I request HealthKit authorization. Why?The most common cause is a missing Info.plist usage-description key: NSHealthShareUsageDescription for reads or…
How do I send the user to fix HealthKit read permissions?You cannot toggle read access from code. Direct the user to Settings, then Privacy & Security, then Health, then your app, where they can…

Why Is Google Health Connect Returning No Data?

Why is Health Connect empty when my code has no errors?Because Health Connect is an on-device store, not a data source. If no app has written the record type you are reading, a correct query…
What causes a SecurityException when reading from Health Connect?A SecurityException on a read almost always means the per-type read permission is either declared in the manifest but not granted at…
Why can I only read the last 30 days of data?By default an app can read Health Connect data from up to about 30 days before any permission was first granted. On Android 14 and later…
What does getSdkStatus tell me?getSdkStatus reports whether Health Connect is usable on the device. SDK_AVAILABLE means you can proceed;…
Does a production build behave differently from my dev build?It can. Apps requesting Health Connect data types must complete the Play Console health apps declaration and pass review, and production…

Why Is My Strava Webhook Not Firing?

How do I check whether my Strava webhook subscription actually exists?Send a GET request to https://www.strava.com/api/v3/push_subscriptions with your client_id and client_secret. If it returns an empty array,…
Why does creating my Strava subscription fail even though my server is running?When you POST to create a subscription, Strava immediately issues a validation GET to your callback_url. If your endpoint does not return…
Can I have more than one Strava webhook subscription per app?No. Each application may have only one subscription, and it receives events for all athletes who authorized the app. If you try to create a…
The webhook fires but my code errors. Is the webhook broken?Usually not. Strava events are lightweight pointers containing fields like object_id and owner_id, not the full activity. Return 200…
Why can't I see private activities from the webhook?Private and hidden activities require the activity:read_all scope, granted at OAuth time. If the athlete authorized only activity:read,…

Why Is Wearable Data Missing or Delayed?

How long should wearable data take to appear?There is no fixed guarantee, but it is near-real-time rather than instant. The device syncs to its phone app on its own schedule (often…
Why do I only get new data and none of the user's history?By default a new connection only delivers data from the moment the user connected forward. Historical data before that point requires a…
The user is connected in Terra but no data arrives. What's wrong?Connected is not the same as has synced. Common causes are that the wearable hasn't synced yet, the user authenticated a different or empty…
Could my webhook be dropping data?Yes. If your endpoint returns a non-2xx status or times out, the provider treats it as a delivery failure and may retry with backoff or…
How do I tell a sync delay apart from a real webhook bug?Check the vendor's own app or dashboard first. If the reading isn't even there, it's a sync issue and no API can have it yet. If it is…

Can't Get Garmin API Access? Here's What's Going On

Why can't I sign up for Garmin API keys?Because Garmin's Connect Developer Program has never been self-serve, and as of 2026 new sign-ups are reportedly paused. The Health and…
Is the Garmin developer program really closed to new applicants?Reportedly yes for new onboarding as of 2026, but treat this as verify rather than certain. Developer forum posts and a public GitHub issue…
Can I use an aggregator like Terra to get Garmin data without approval?Often yes. Aggregators such as Terra hold their own Garmin partnership and let users connect their Garmin account through the aggregator's…
What are my alternatives while Garmin access is blocked?Read Garmin data from Apple HealthKit or Google Health Connect on the phone, pull Garmin activities that re-sync into Strava once a user…
How long does Garmin approval take once the form is open?Plan for weeks, not hours. Approval is a manual, partner-level business review with no guaranteed timeline, and there is no self-serve…

Google Fit API Is Deprecated — What to Use Instead

When exactly is the Google Fit API being shut down?All Google Fit APIs, including the REST API, the Android SDK, and the BLE APIs, are supported only until the end of 2026. New signups have…
Is there a drop-in replacement for the Fit REST API?No. Google states there is no alternative that maps one-to-one onto the Fit REST API, so you cannot simply swap a base URL. Cloud and…
Should I migrate to Health Connect or the Google Health API?It depends on how you used Fit. On-device reads of steps and aggregates on Android move to Health Connect, while cloud, account, and OAuth…
Where do Fitbit Web API integrations go?The Fitbit cloud surface is folding into the Google Health API, which is the same destination as Fit's cloud APIs. As of 2026 the Google…
What about Google Fit on Wear OS?Fit's Wear OS sensor and activity APIs move to Health Services on Wear OS, not to Health Connect. Health Connect is the phone-side…

Oura Personal Access Tokens Are Deprecated — Here's the Fix

Can I still create an Oura Personal Access Token?No — as of the December 2025 deprecation, new Personal Access Tokens can no longer be created, and new integrations must use OAuth 2.0…
Do my Oura API endpoints change when I move from a PAT to OAuth?No. The v2 REST base at api.ouraring.com/v2/ and the usercollection endpoints are unchanged, and the responses are the same. What changes…
Is there a simpler path than OAuth for a personal Oura project?Not from Oura directly anymore — OAuth is the supported route for new integrations, even single-user ones, so you register an app and…

Fitbit Error Code 401: What It Means and How to Fix It

How long does a Fitbit access token last before it expires?A Fitbit token response includes expires_in with a value of 28800 seconds, which is eight hours. That is the commonly documented lifetime,…
Does refreshing a Fitbit token require HTTP Basic auth?It depends on the OAuth 2.0 application type you registered. Public Client apps, such as mobile and single-page apps that ship no secret,…
What does Fitbit put in the response body when it rejects a call?Fitbit returns an errors array, and the field to read is errorType. The two values you will see most on a rejected credential are…
Why does a Fitbit token that works in one of my apps fail in another?Every Fitbit app registration gets its own Client ID, and a token minted under one registration is not valid for another. The token is…
Does a Fitbit 401 mean the user disconnected my app?Sometimes, and the refresh call is what tells you. If the refresh succeeds, the original failure was ordinary token ageing and the…

HealthKit Authorization Denied: What It Means and What It Hides

Does sharingDenied mean my HealthKit reads will fail too?No. Apple documents authorizationStatus(for:) as checking the status for saving data to the HealthKit store, and the enum describes whether…
What does getRequestStatusForAuthorization actually tell me?Apple describes it as indicating whether the system presents a permission sheet if your app requests authorization for the provided types.…
Why does calling requestAuthorization again show no permission sheet?Apple documents that if the user has already chosen to grant or prohibit access to all of the types specified, HealthKit returns the…
How do I know if a user granted only a limited window of health history?Apple's authorization sheet includes a second screen where people choose between a recent limited window and their full history. Call…
Why do HealthKit writes fail on Vision Pro when my status check says authorized?In a Guest User session, Apple documents that an app's permissions do not change, so authorizationStatus(for:) still reports the owner's…

Strava API 401 Unauthorized: What It Means and How to Fix It

What does Strava's Authorization Error response body tell me?It tells you Strava rejected the credential rather than the request. Our corpus records the shape as a message of Authorization Error…
Does a missing activity:read_all scope make Strava return 401?No, and this is the Strava-specific trap. On Strava a scope shortfall usually shows up as missing data rather than an error status. Plain…
Do Strava token refresh calls count against my rate limit?No. Our Strava integration guide records that the OAuth token exchange and refresh calls do not count against your API rate limit. That…
How do I tell a deauthorized athlete from an expired Strava token?The refresh call is the test. If the refresh succeeds, the original rejection was ordinary ageing and the connection is intact. If it comes…
Could Strava's developer subscription requirement be causing my 401s?Treat that as unproven rather than as a cause. Strava's developer program has tightened since 2024 with formal Standard and Extended Access…

HealthKit Background Delivery Not Working: Why Your Observer Never Fires

Why does enableBackgroundDelivery fail with errorAuthorizationDenied when the user already granted access?Because that error is about your entitlement, not the person's choice. Apple documents that for iOS 15 and watchOS 8 and later you must…
My observer query fires but finds nothing new. What is wrong?Probably nothing, because an observer query is not designed to carry data. Apple states that the update handler does not receive any…
Which HealthKit types can be registered for background delivery?Apple documents the type parameter as accepting an HKCharacteristicType, HKQuantityType, HKCategoryType, or HKWorkoutType, and states…
Why does my observer query never fire in the iOS Simulator?Because Apple does not support it there. The sentence appears on both the enableBackgroundDelivery reference and the HKObserverQuery…
How many background updates can a watchOS app receive in an hour?Apple documents that in watchOS, background updates share a budget with WKApplicationRefreshBackgroundTask tasks, and that your app can…

HealthKit errorDatabaseInaccessible: Reads Fail While the Device Is Locked

Why does my background HealthKit read fail when the same query works in the app?Because the device was locked when the background job ran. Apple's documentation states this error occurs when your app queries HealthKit…
Can my app still save HealthKit data while the device is locked?Apple's discussion states that you can still save data while the device is locked. It says the data is written into a temporary file, which…
Should I retry immediately after errorDatabaseInaccessible?As a practice, no. A tight retry loop burns your background execution window against a device that may stay locked for hours. Classify the…

HealthKit errorHealthDataUnavailable: The Device Does Not Support HealthKit

What does errorHealthDataUnavailable actually mean?Apple's abstract states that the user accessed HealthKit on an unsupported device. It is a capability fact about the hardware or platform,…
Where should the HealthKit availability check go?Apple's discussion says to verify support before calling any other HealthKit method. In practice that means every entry point, not just app…
Does this error mean HealthKit never works on iPad?Apple's discussion gives iPad as an example of a device an iOS app can run on that does not support HealthKit. That is an example, not a…

HealthKit errorHealthDataRestricted: An MDM Profile Turned HealthKit Off

Can my app do anything about a HealthKit MDM restriction?No. Apple's abstract describes it as a Mobile Device Management profile restricting the use of HealthKit on the device. There is no API to…
How do I tell a restricted device from an unsupported one?By the error case, which is why they need separate log lines. Apple describes errorHealthDataRestricted as a management-profile restriction…
What should I show a user on a managed device?As a practice, an explanation rather than an error. Say that this device's management profile has Health access turned off, that automatic…

HealthKit errorNoData: The Query Ran and Found Nothing

Is errorNoData a bug in my query?Usually not. Apple's abstract states that data is unavailable for the requested query and predicate, and the discussion says no data exists…
How is this different from a HealthKit query that returns an empty array?An empty array carries no error and no information: a denied read looks exactly like a type with no samples, because Apple hides read…
Should I ask the user for permission when I get errorNoData?No. The error can arrive with permissions in perfect order, and re-requesting authorization after the user has already decided does not…

HealthKit errorInvalidArgument: Finding the Argument HealthKit Rejected

What does Apple say causes errorInvalidArgument?Only that the app passed an invalid argument to the HealthKit API. That abstract is the entire published description; there is no…
Why do cumulative and discrete types cause invalid arguments?Because the aggregation you ask for has to be one the type can define. A type that accumulates over an interval supports a running total; a…
Should I catch errorInvalidArgument and return an empty result?No. Unlike a locked store or an unsupported device, a rejected argument will be rejected the same way forever, so catching it silently…

HealthKit errorAuthorizationNotDetermined: You Called Before You Asked

Does not determined mean the user denied my app?No. Apple's abstract states the app has not yet asked the user for the authorization required to complete the task. Nobody has made a…
Why does this happen when my onboarding already requests authorization?Because your onboarding is not the only way into HealthKit code. Widgets, extensions, background delivery wake-ups, a watch app launched…
Can I just request authorization again to clear it?Requesting is exactly right when the state really is not determined. It is the wrong reflex once decisions have been made: Apple documents…

HealthKit errorRequiredAuthorizationDenied: Clinical Records Are a Separate Class

Why does authorization fail even though the user allowed most types?Because the required set is all or nothing. Apple's abstract states the user has not granted authorization to access all the required…
Can I find out which clinical record type the user refused?No. Apple states that the system does not tell your app which record types the person denied access to, which is quoted in our HealthKit…
How is this different from ordinary HealthKit authorization?Ordinary types are declared in the request, decided independently, and refusals on the read side are invisible by design. Required clinical…

HealthKit Workout Session Errors: Four Cases, Two of Them Undocumented

Can two apps run a workout session at the same time?Apple's discussion states that Apple Watch only runs one workout session at a time. If the user begins a second session in a different app,…
Should my app restart the session automatically after this error?As a practice, no. Restarting takes the session back from whichever app the user just chose, and if that app is written the same way the…
What do the two undocumented workout errors mean?Apple publishes no abstract and no discussion for errorBackgroundWorkoutSessionNotAllowed or errorWorkoutActivityNotAllowed, so the honest…

HealthKit errorNotPermissibleForGuestUserMode: Writes Blocked in a Guest Session

Why does my authorization status say authorized when the save fails?Because the status belongs to the device owner. Apple states that in a Guest User session an app's permissions do not change, so the value…
Should I show the guest an error when a HealthKit write fails?Usually not. Apple suggests silently ignoring the error for passive or periodic saves, and alerting only when the guest took an action that…
Can a guest still read HealthKit data?Apple states that a guest can read data the owner already authorized, but cannot authorize additional types, and that the authorization…

Undocumented HealthKit Errors: Handling a Case Apple Never Described

Which HealthKit error cases has Apple not documented?unknownError, errorDataSizeExceeded, errorBackgroundWorkoutSessionNotAllowed, and errorWorkoutActivityNotAllowed are published as type…
Can I infer what errorDataSizeExceeded means from its name?You can use the name to decide where to look, and no further. A sensible investigation is to examine what your app just tried to write and…
How should my app handle an unknown HealthKit error code?Log the raw domain and numeric code together with the operation and type identifier, keep the data you were trying to write and mark it…

Back to the Troubleshooting hub, or see every question this site answers.