SDK 3 - Error Codes Reference - Mindset AI Documentation

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

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.

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

SDK_ERR_1002 - Token Expired

Cause: Token has expired. Solution: Implement token refresh:

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 }:

// ✅ 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:

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

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:

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
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 [email protected] 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

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 [email protected], include:

Error Code

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

Page URL

The URL where the error occurred

Browser Information

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

Console Logs

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

Steps to Reproduce

What you did immediately before the error appeared

How to copy console logs:

Open browser developer tools (F12 or right-click → Inspect)
Go to the Console tab
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:

// 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:

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

Network Problems (1031-1033)

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

Can you access other websites?
Are you behind a corporate firewall?
Check status.firebase.google.com for outages

Troubleshooting Workflow

Note the error code

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

Find the error above

Use the Quick Reference table to locate your error category

Check the solution

Follow the specific solution steps for your error code

Check browser console

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

Contact support if needed

If the solution doesn’t resolve the issue, contact [email protected] 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.

Overview

Integrate Agent Chat SDK 3

Integrate Agent Chat SDK 2

MCP Server Integration

AMS SDK Integration

API Overview

API playground

Webhooks

​Overview

​Quick Reference

​Authentication Errors (1001-1006)

​SDK_ERR_1001 - Authentication Failed

​SDK_ERR_1002 - Token Expired

​SDK_ERR_1003 - Token Invalid

​SDK_ERR_1004 - Token Missing

​SDK_ERR_1005 - Anonymous Access Denied

​SDK_ERR_1006 - URL Not Whitelisted

​Agent Configuration Errors (1011-1014)

​SDK_ERR_1011 - Agent Configuration Missing

​SDK_ERR_1012 - Agent Not Found

​SDK_ERR_1013 - Agent Configuration Invalid

​SDK_ERR_1014 - Agent Inactive

​Data Loading Errors (1021-1024)

​SDK_ERR_1021 - Application Model Load Failed

​SDK_ERR_1022 - User Model Load Failed

​SDK_ERR_1023 - Agent Model Load Failed

​SDK_ERR_1024 - Required Models Not Loaded

​Network Errors (1031-1033)

​SDK_ERR_1031 - Network Timeout

​SDK_ERR_1032 - Network Connection Failed

​SDK_ERR_1033 - Firestore Connection Failed

​Permission Errors (1041-1042)

​SDK_ERR_1041 - Firestore Permission Denied

​SDK_ERR_1042 - Application Access Denied

​General Error

​SDK_ERR_1000 - Unknown Error

​Error Display Behavior

​Reporting to Support

​Common Error Patterns

​Authentication Issues (1001-1006)

​Agent Not Loading (1011-1014)

​Network Problems (1031-1033)

​Troubleshooting Workflow

​Error Code Categories Explained

​Authentication (1001-1006)

​Agent Configuration (1011-1014)

​Data Loading (1021-1024)

​Network/Connection (1031-1033)

​Permissions (1041-1042)

Overview

Quick Reference

Authentication Errors (1001-1006)

SDK_ERR_1001 - Authentication Failed

SDK_ERR_1002 - Token Expired

SDK_ERR_1003 - Token Invalid

SDK_ERR_1004 - Token Missing

SDK_ERR_1005 - Anonymous Access Denied

SDK_ERR_1006 - URL Not Whitelisted

Agent Configuration Errors (1011-1014)

SDK_ERR_1011 - Agent Configuration Missing

SDK_ERR_1012 - Agent Not Found

SDK_ERR_1013 - Agent Configuration Invalid

SDK_ERR_1014 - Agent Inactive

Data Loading Errors (1021-1024)

SDK_ERR_1021 - Application Model Load Failed

SDK_ERR_1022 - User Model Load Failed

SDK_ERR_1023 - Agent Model Load Failed

SDK_ERR_1024 - Required Models Not Loaded

Network Errors (1031-1033)

SDK_ERR_1031 - Network Timeout

SDK_ERR_1032 - Network Connection Failed

SDK_ERR_1033 - Firestore Connection Failed

Permission Errors (1041-1042)

SDK_ERR_1041 - Firestore Permission Denied

SDK_ERR_1042 - Application Access Denied

General Error

SDK_ERR_1000 - Unknown Error

Error Display Behavior

Reporting to Support

Common Error Patterns

Authentication Issues (1001-1006)

Agent Not Loading (1011-1014)

Network Problems (1031-1033)

Troubleshooting Workflow

Error Code Categories Explained

Authentication (1001-1006)

Agent Configuration (1011-1014)

Data Loading (1021-1024)

Network/Connection (1031-1033)

Permissions (1041-1042)