# SDK 3 - Error Codes Reference

> You're reading the Mindset v3 documentation. v3 is no longer sold; this is reference for existing customers. Mindset 4 docs are at /docs.

Complete reference for SDK initialization and runtime error codes

## Overview

When an initialization error occurs, users see a generic error message with a specific error code that can be copied and shared with support.

Users see the same message for all errors—only the error code differs. This keeps the user experience simple while allowing developers and support teams to identify the specific issue.

**Error Code Format:** `SDK_ERR_XXXX,` where the number indicates the category.

## Quick Reference

| Code Range | Category            |
| ---------- | ------------------- |
| 1000       | General/Unknown     |
| 1001-1006  | Authentication      |
| 1011-1014  | Agent Configuration |
| 1021-1024  | Data Loading        |
| 1031-1033  | Network/Connection  |
| 1041-1042  | Permissions         |

> **Tip:** Know your error code? Use the Quick Reference table above to jump to the relevant category.

## Authentication Errors (1001-1006)

### SDK_ERR_1001 - Authentication Failed

**Cause:** Token validation failed.

**Solution:** Verify your `fetchAuthentication` returns a valid token object.

```javascript
fetchAuthentication: async () => {
  const token = await yourAuthService.getToken();
  return { token };
}
```

### SDK_ERR_1002 - Token Expired

**Cause:** Token has expired.

**Solution:** Implement token refresh:

```javascript
fetchAuthentication: async () => {
  const token = await yourAuthService.getOrRefreshToken();
  return { token };
}
```

### SDK_ERR_1003 - Token Invalid

**Cause:** Token is malformed.

**Solution:** Check you're returning the correct token format from your auth service.

### SDK_ERR_1004 - Token Missing

**Cause:** No token provided.

**Solution:** Ensure `fetchAuthentication` returns `{ token: string }`:

```javascript
// ✅ Correct
fetchAuthentication: async () => ({ token: 'your-token' })

// ❌ Wrong - missing token property
fetchAuthentication: async () => ('your-token')
```

### SDK_ERR_1005 - Anonymous Access Denied

**Cause:** Agent requires authentication.

**Solution:** Either provide `fetchAuthentication` or enable anonymous access in Agent Management Studio.

### SDK_ERR_1006 - URL Not Whitelisted

**Cause:** Current domain not in anonymous access safelist.

**Solution:** Add your domain in Agent Management Studio or use authenticated access.

## Agent Configuration Errors (1011-1014)

### SDK_ERR_1011 - Agent Configuration Missing

**Cause:** Agent not configured.

**Solution:** Verify the agent exists and is published in Agent Management Studio.

### SDK_ERR_1012 - Agent Not Found

**Cause:** No agent with specified `agentUid`.

**Solution:** Check for typos—the UID is case-sensitive:

```html
<mindset-agent agentUid="Your-Exact-Agent-UID"></mindset-agent>
```

> **Warning:** Agent UIDs are case-sensitive. `my-agent-uid` and `My-Agent-UID` are different agents.

### SDK_ERR_1013 - Agent Configuration Invalid

**Cause:** Agent configuration is corrupted.

**Solution:** Review settings in Agent Management Studio or recreate the agent.

### SDK_ERR_1014 - Agent Inactive

**Cause:** Agent is disabled or unpublished.

**Solution:** Activate the agent in Agent Management Studio.

## Data Loading Errors (1021-1024)

### SDK_ERR_1021 - Application Model Load Failed

**Cause:** Invalid `appUid` or application deleted.

**Solution:** Verify the ID in your `init` call:

```javascript
window.mindset.init({
  appUid: 'your-correct-app-uid', // Check this
});
```

### SDK_ERR_1022 - User Model Load Failed

**Cause:** User profile couldn't be loaded.

**Solution:** Verify the auth token corresponds to a valid user.

### SDK_ERR_1023 - Agent Model Load Failed

**Cause:** Agent data couldn't be loaded.

**Solution:** Check agent setup is complete in Agent Management Studio.

### SDK_ERR_1024 - Required Models Not Loaded

**Cause:** Multiple data loads failed.

**Solution:** Check network connection and refresh the page.

## Network Errors (1031-1033)

### SDK_ERR_1031 - Network Timeout

**Cause:** Request took too long.

**Solution:** Check internet connection and try again.

### SDK_ERR_1032 - Network Connection Failed

**Cause:** No connection to Mindset AI services.

**Solution:** Verify internet connectivity and firewall settings.

### SDK_ERR_1033 - Firestore Connection Failed

**Cause:** Database connection failed.

**Solution:** Check the following:

- Internet connectivity
- Firebase status at [status.firebase.google.com](https://status.firebase.google.com)
- Firewall allows `*.firebaseio.com` and `*.googleapis.com`

## Permission Errors (1041-1042)

### SDK_ERR_1041 - Firestore Permission Denied

**Cause:** User lacks permission to access data.

**Solution:** Check user roles and permissions in Agent Management Studio.

### SDK_ERR_1042 - Application Access Denied

**Cause:** User not authorized for this application.

**Solution:** Verify user access settings in Agent Management Studio.

## General Error

### SDK_ERR_1000 - Unknown Error

**Cause:** Unexpected error.

**Solution:** Check browser console for details and contact <support@mindset.ai> if issue persists.

## Error Display Behavior

The SDK handles errors differently depending on when and where they occur:

| Error Type         | Display                               | User Action                |
| ------------------ | ------------------------------------- | -------------------------- |
| **Initialization** | Full-screen overlay with error code   | Copy code, contact support |
| **Conversation**   | In-chat message after 10 auto-retries | Click "Retry" button       |

> **Note:** The SDK automatically retries conversation errors up to 10 times before showing the error UI, handling most transient network issues silently.

## Reporting to Support

When contacting <support@mindset.ai>, include:

### 1. Error Code

The specific error code (e.g., `SDK_ERR_1012`)

### 2. Page URL

The URL where the error occurred

### 3. Browser Information

Browser name and version (e.g., Chrome 120, Safari 17)

### 4. Console Logs

Any additional errors from browser developer tools (press F12 → Console tab)

### 5. Steps to Reproduce

What you did immediately before the error appeared

> **Tip:** **How to copy console logs:**
>
> 1. Open browser developer tools (F12 or right-click → Inspect)
> 2. Go to the Console tab
> 3. Right-click in the console and select "Save as..." or copy the error messages

## Common Error Patterns

### Authentication Issues (1001-1006)

**Most common cause:** Token format is incorrect or `fetchAuthentication` doesn't return the right structure.

**Quick check:**

```javascript
// Your fetchAuthentication should return this exact format:
{ token: 'your-token-string' }
```

### Agent Not Loading (1011-1014)

**Most common cause:** Typo in `agentUid` or agent not published.

**Quick check:**

1. Copy the agent UID directly from Agent Management Studio
2. Paste it into your code (don't type it manually)
3. Verify the agent is published (not draft)

### Network Problems (1031-1033)

**Most common cause:** Firewall blocking Firebase or network connectivity issues.

**Quick check:**

1. Can you access other websites?
2. Are you behind a corporate firewall?
3. Check [status.firebase.google.com](https://status.firebase.google.com) for outages

## Troubleshooting Workflow

### 1. Note the error code

Copy the error code shown to the user (e.g., `SDK_ERR_1012`)

### 2. Find the error above

Use the Quick Reference table to locate your error category

### 3. Check the solution

Follow the specific solution steps for your error code

### 4. Check browser console

Open developer tools (F12) and check the Console tab for additional details

### 5. Contact support if needed

If the solution doesn't resolve the issue, contact <support@mindset.ai> with the information listed in "Reporting to Support"

## Error Code Categories Explained

### Authentication (1001-1006)

Errors related to user authentication, token validation, and access control.

### Agent Configuration (1011-1014)

Errors related to agent setup, publishing status, and configuration validity.

### Data Loading (1021-1024)

Errors that occur when the SDK tries to load application, user, or agent data.

### Network/Connection (1031-1033)

Errors related to network connectivity, timeouts, and database connections.

### Permissions (1041-1042)

Errors related to user permissions and access rights.