Error Reference

Complete reference of error codes and how to handle them.

Error Response Format

All errors follow this format:

{
  "error": "error_code",
  "message": "Human-readable description",
  "detail": "Additional context (optional)"
}

Authentication Errors

otp_start_failed

Cause: Failed to send OTP
HTTP Status: 400

{
  "error": "otp_start_failed",
  "detail": "phone must be E.164 (e.g., +14155551234)"
}

Solutions:

• Verify phone number is in E.164 format
• Check that country code is included
• Remove spaces, dashes, parentheses

invalid_code

Cause: OTP code is incorrect
HTTP Status: 401

{
  "error": "invalid_code"
}

Solutions:

• Ask user to re-enter the code
• Check for typos
• Ensure code hasn't been used already

code_expired

Cause: OTP code has expired (>10 minutes)
HTTP Status: 401

Solutions:

• Request a new OTP
• Prompt user to start over

rate_limited

Cause: Too many OTP requests
HTTP Status: 429

Solutions:

• Wait 60 seconds before retrying
• Show countdown timer to user
• Limit UI retries

unauthorized

Cause: Invalid or expired JWT token
HTTP Status: 401

{
  "error": "unauthorized",
  "message": "Invalid or missing authentication"
}

Solutions:

• Re-authenticate the user
• Check if token is properly formatted
• Verify token hasn't expired (30 days)

token_expired

Cause: JWT token has expired
HTTP Status: 401

Solutions:

• Clear stored credentials
• Re-authenticate with new OTP

Memory Errors

missing_user_id

Cause: user_id parameter not provided
HTTP Status: 400

{
  "error": "missing_user_id"
}

Solutions:

• Include user_id in request body or query params
• Verify user is authenticated

missing_fields

Cause: Required fields missing
HTTP Status: 400

{
  "error": "missing_fields",
  "required": ["user_id", "query"]
}

Solutions:

• Check the required array
• Add all required fields to request

missing_key_or_value

Cause: Remember call missing key or value
HTTP Status: 400

Solutions:

• Provide both key and value to remember endpoint
• Keys and values must be non-empty strings

pod_fetch_failed

Cause: Failed to retrieve Memory Profile
HTTP Status: 500

Solutions:

• Retry the request
• Check if user exists
• Contact support if persistent

remember_failed

Cause: Failed to save memory
HTTP Status: 500

Solutions:

• Retry the request
• Verify key and value are valid strings
• Check for special characters in key

Tool Errors

tool_not_configured

Cause: Tool's auth config not set up
HTTP Status: 400

{
  "error": "tool_not_configured",
  "message": "gmail auth config not set. Add COMPOSIO_GMAIL_AUTH_CONFIG_ID to .env"
}

Solutions:

• Server-side configuration issue
• Contact app developer

invalid_tool

Cause: Unknown tool type
HTTP Status: 400

Solutions:

• Use valid tool types: gmail, calendar, drive, notion

tool_not_connected

Cause: Tool not connected for this user
HTTP Status: 400

Solutions:

• Guide user to connect the tool first
• Check connected_tools array in profile

connection_not_found

Cause: OAuth connection not found after callback
HTTP Status: 400

{
  "error": "connection_not_found",
  "message": "Could not find connection after multiple attempts. Please try again."
}

Solutions:

• User may have closed OAuth window
• OAuth may have timed out
• Retry the connection flow

connection_not_active

Cause: OAuth completed but connection not active
HTTP Status: 400

{
  "error": "connection_not_active",
  "status": "PENDING"
}

Solutions:

• Wait and retry (OAuth can take time to process)
• User may have denied permissions
• Retry connection flow

insufficient_permissions

Cause: User didn't grant required permissions
HTTP Status: 200 (with partialPermissions: true)

{
  "success": false,
  "connected": false,
  "partialPermissions": true,
  "message": "Please grant all required permissions for gmail"
}

Solutions:

• Explain required permissions to user
• Have user reconnect and grant all permissions

connect_failed

Cause: OAuth initiation failed
HTTP Status: 500

Solutions:

• Check API key is valid
• Retry the connection
• Contact support

sync_failed

Cause: Tool sync failed
HTTP Status: 500

Solutions:

• Verify tool is still connected
• User may have revoked access
• Retry after checking connection

Search Errors

search_failed

Cause: Search operation failed
HTTP Status: 500

Solutions:

• Check tool is connected
• Verify query is valid
• Retry request

gmail_not_connected

Cause: Gmail search called but Gmail not connected
HTTP Status: 400

Solutions:

• Guide user to connect Gmail
• Check connected_tools before searching

calendar_not_connected

Cause: Calendar search called but Calendar not connected
HTTP Status: 400

Solutions:

• Guide user to connect Calendar

Streaming Errors

Streaming errors are returned as SSE events:

// Error event
data: {"type": "error", "message": "Stream failed"}

Common Streaming Errors

Message	Cause	Solution
Stream request failed: 401	Auth failed	Re-authenticate
Stream request failed: 400	Invalid request	Check parameters
Unknown stream error	Connection lost	Retry

Handling Errors

TypeScript Pattern

import { MemoryClient } from '@configure/memory-sdk';

async function safeMemoryOperation(
  client: MemoryClient,
  token: string,
  userId: string
) {
  try {
    return await client.memory.getProfile(token, userId);
  } catch (error) {
    const message = error.message || 'Unknown error';
    
    // Authentication errors
    if (message.includes('unauthorized') || message.includes('token_expired')) {
      throw new AuthExpiredError('Please log in again');
    }
    
    // Validation errors
    if (message.includes('missing_')) {
      throw new ValidationError(`Missing required field: ${message}`);
    }
    
    // Rate limiting
    if (message.includes('rate_limited')) {
      throw new RateLimitError('Too many requests. Please wait.');
    }
    
    // Server errors
    if (message.includes('failed')) {
      throw new ServerError('Something went wrong. Please try again.');
    }
    
    throw error;
  }
}

Python Pattern

def safe_memory_operation(client, token, user_id):
    try:
        return client.memory.get_profile(token, user_id)
    except Exception as e:
        message = str(e)
        
        if "unauthorized" in message or "token_expired" in message:
            raise AuthExpiredError("Please log in again")
        
        if "missing_" in message:
            raise ValidationError(f"Missing required field: {message}")
        
        if "rate_limited" in message:
            raise RateLimitError("Too many requests. Please wait.")
        
        if "failed" in message:
            raise ServerError("Something went wrong. Please try again.")
        
        raise

React Hook Pattern

function useMemory() {
  const [error, setError] = useState<string | null>(null);
  
  const handleError = (error: Error) => {
    const message = error.message;
    
    if (message.includes('unauthorized')) {
      // Clear auth state and redirect to login
      clearAuth();
      router.push('/login');
      return;
    }
    
    if (message.includes('rate_limited')) {
      setError('Too many requests. Please wait a moment.');
      return;
    }
    
    setError('Something went wrong. Please try again.');
  };
  
  return { error, handleError };
}

HTTP Status Code Summary

Status	Meaning	Common Causes
200	Success	Request completed
400	Bad Request	Missing/invalid parameters
401	Unauthorized	Invalid token, expired auth
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limited
500	Server Error	Internal error, retry
503	Service Unavailable	Service down, retry later

Getting Help

If you encounter persistent errors:

1. Check the error code and message
2. Verify your API key and token
3. Check the API status page
4. Contact support at support@configure.dev with:
   • Error code and message
   • Request details (endpoint, parameters)
   • Timestamp of the error