> ## Documentation Index
> Fetch the complete documentation index at: https://openwearables.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Error Handling

> Reference for Open Wearables API error codes, response formats, and resolution steps. Covers auth failures, validation errors, rate limits, and 404s.

## Authentication Errors

### Missing Authentication

```json theme={null}
{
  "detail": "Authentication required: provide JWT token or API key"
}
```

**Cause:** No API key provided in the request.

**Solution:** Include the API key header:

```bash theme={null}
-H "X-Open-Wearables-API-Key: YOUR_API_KEY"
```

<Warning>
  Use `X-Open-Wearables-API-Key` header, **not** `Authorization: Bearer`.
</Warning>

### Invalid API Key

```json theme={null}
{
  "detail": "Invalid or missing 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

```json theme={null}
{
  "detail": "Could not validate credentials"
}
```

**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

```json theme={null}
{
  "detail": "User not connected to garmin"
}
```

**Cause:** Attempting to sync or fetch data from a provider the user hasn't connected yet.

**Solution:** Complete the OAuth flow first:

```bash theme={null}
GET /api/v1/oauth/garmin/authorize?user_id={user_id}
```

### Token Expired

```json theme={null}
{
  "detail": "Token expired and no refresh token available for garmin"
}
```

Or:

```json theme={null}
{
  "detail": "Garmin authorization expired. Please re-authorize."
}
```

**Cause:** The OAuth token for this provider has expired and cannot be refreshed.

**Solution:** User needs to reconnect via OAuth:

```bash theme={null}
GET /api/v1/oauth/garmin/authorize?user_id={user_id}
```

### Provider Doesn't Support OAuth

```json theme={null}
{
  "detail": "Provider 'apple' does not 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

```json theme={null}
{
  "detail": "Input should be 'apple', 'garmin', 'polar' or 'suunto'"
}
```

**Cause:** Provider name is invalid or has wrong case.

**Solution:** Use lowercase provider names: `garmin`, `polar`, `suunto`, `apple`.

***

## Validation Errors

### Missing Required Field

```json theme={null}
{
  "detail": "Field required"
}
```

**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 endpoints
* `start_date` and `end_date` for event endpoints
* `user_id` for OAuth authorization

### Invalid UUID Format

```json theme={null}
{
  "detail": "Input should be a valid UUID, invalid character: expected an optional prefix of `urn:uuid:` followed by [0-9a-fA-F-], found `n` at 1"
}
```

**Cause:** A UUID parameter (like `user_id`) has an invalid format.

**Solution:** Ensure UUIDs are in the correct format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`

***

## Resource Errors

### Resource Not Found

```json theme={null}
{
  "detail": "User with ID: {id} 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

| Status | Meaning       | Common Causes                         |
| ------ | ------------- | ------------------------------------- |
| 200    | Success       | Request completed successfully        |
| 201    | Created       | Resource created successfully         |
| 400    | Bad Request   | Invalid parameters, validation errors |
| 401    | Unauthorized  | Missing or invalid authentication     |
| 404    | Not Found     | Resource doesn't exist                |
| 422    | Unprocessable | Request body validation failed        |
| 500    | Server Error  | Internal error (please report)        |