Authentication Errors
Missing Authentication
Cause: No API key provided in the request.
Solution: Include the API key header:
Use X-Open-Wearables-API-Key header, not Authorization: Bearer.
Invalid API Key
Cause: The provided API key doesn’t exist or has been revoked.
Solution: Verify your API key is correct and active in the developer portal.
Protected Endpoint
Cause: Attempting to access an endpoint that requires developer JWT authentication (not just an API key).
Solution: Some operations (like deleting users) require logging in via the developer portal. Use JWT authentication for these endpoints.
Provider Errors
User Not Connected
Cause: Attempting to sync or fetch data from a provider the user hasn’t connected yet.
Solution: Complete the OAuth flow first:
Token Expired
Or:
Cause: The OAuth token for this provider has expired and cannot be refreshed.
Solution: User needs to reconnect via OAuth:
Provider Doesn’t Support OAuth
Cause: Attempting to use OAuth with a push-only provider like Apple Health.
Solution: Apple Health data is pushed from the device, not pulled via OAuth. Use the SDK sync or import endpoints instead.
Invalid Provider Name
Cause: Provider name is invalid or has wrong case.
Solution: Use lowercase provider names: garmin, polar, suunto, apple.
Validation Errors
Missing Required Field
Cause: A required query parameter or request body field is missing.
Solution: Check the API documentation for required parameters. Common required fields:
start_time and end_time for timeseries endpointsstart_date and end_date for event endpointsuser_id for OAuth authorization
Cause: A UUID parameter (like user_id) has an invalid format.
Solution: Ensure UUIDs are in the correct format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SDK Sync Payloads (Async Validation)
POST /api/v1/sdk/users/{user_id}/sync returns 202 Accepted immediately and validates/imports the payload in a background worker. A malformed record does not produce a synchronous 400/422 — validation failures are surfaced via the batch’s sync status (and internal error reporting), not the HTTP response. The endpoint returns 400 only for an unsupported provider.
Resource Errors
Resource Not Found
Cause: The requested resource (user, connection, etc.) doesn’t exist.
Solution: Verify the ID is correct and the resource was created.
HTTP Status Code Reference
