# Troubleshooting

Common issues and solutions.

***

## API Issues

### 403 CLIENT\_SECRET\_REQUIRED

You're calling an endpoint that requires `X-Client-Secret` but the header is missing.

```
Fix: Add X-Client-Secret header to your request
```

### 403 CONNECTION\_NOT\_SHARED

The connection ID you're querying hasn't been shared with your client.

```
Fix: The user needs to open the widget and click "Share" on that connection
```

### 404 USER\_NOT\_FOUND

No user mapping exists for the `external_user_id` you provided.

```
Fix: The user needs to open the widget, complete OTP, and the bind will happen automatically
```

### 400 MISSING\_LINK\_TOKEN

The endpoint requires an `X-Link-Token` header (e.g., GET /v1/users/share).

```
Fix: Create a link token first via POST /v1/link/token
```

### 409 USER\_ALREADY\_BOUND

The `external_user_id` in the link token is already bound to a different Sync user.

```
This happens when:
- Two different phone numbers tried to bind with the same external_user_id
- The mapping was created with a truncated user ID

Fix: Contact support to reset the mapping
```

### 429 TOO\_MANY\_REQUESTS

Rate limit exceeded (100 req/min per client).

```
Fix: Wait for the Retry-After period, then retry
```