Error Handling

Proper error handling makes your agents reliable and helps users understand what went wrong.

Return Values

Success

Return the data directly:

return {
  temperature: 72,
  condition: 'Sunny',
  city: 'London',
};

Error

Return an error object:

return {
  error: true,
  message: 'City not found',
};

Requires Authentication

For OAuth agents when not connected:

return {
  error: true,
  message: 'Please connect your account first',
  requiresAuth: true,
};

Error Types

Validation Errors

Check input parameters:

async function handler(input, context) {
  const { city } = input;
  
  if (!city) {
    return { error: true, message: 'City is required' };
  }
  
  if (typeof city !== 'string') {
    return { error: true, message: 'City must be a string' };
  }
  
  // Continue...
}

Missing Secrets

Check for required secrets:

const apiKey = context.secrets.API_KEY;

if (!apiKey) {
  return { 
    error: true, 
    message: 'API key not configured. Please add your API key in plugin settings.' 
  };
}

API Errors

Handle HTTP errors:

const response = await context.fetch(url);

if (!response.ok) {
  // Try to get error details from response
  let errorMessage = `Request failed with status ${response.status}`;
  
  try {
    const errorData = JSON.parse(response.body);
    if (errorData.message) {
      errorMessage = errorData.message;
    }
  } catch {
    // Response wasn't JSON
  }
  
  return { error: true, message: errorMessage };
}

Network Errors

Catch exceptions:

try {
  const response = await context.fetch(url);
  // ...
} catch (error) {
  return { 
    error: true, 
    message: error.message || 'Network request failed' 
  };
}

Full Pattern

async function handler(input, context) {
  // 1. Validate input
  const { action, query } = input;
  
  if (!action) {
    return { error: true, message: 'Action is required' };
  }
  
  // 2. Check OAuth (for connectors)
  if (!await context.oauth.isConnected()) {
    return { error: true, requiresAuth: true };
  }
  
  // 3. Check secrets (for API-key tools)
  const apiKey = context.secrets.API_KEY;
  if (!apiKey) {
    return { error: true, message: 'API key not configured' };
  }
  
  // 4. Make request with error handling
  try {
    const response = await context.fetch(url);
    
    // 5. Handle HTTP errors
    if (!response.ok) {
      return handleApiError(response);
    }
    
    // 6. Parse response
    const data = JSON.parse(response.body);
    
    // 7. Return success
    return { success: true, data };
    
  } catch (error) {
    // 8. Handle exceptions
    return { 
      error: true, 
      message: error.message || 'Request failed' 
    };
  }
}

function handleApiError(response) {
  const statusMessages = {
    400: 'Invalid request',
    401: 'Authentication failed',
    403: 'Access denied',
    404: 'Not found',
    429: 'Rate limited - please try again later',
    500: 'Server error',
  };
  
  const message = statusMessages[response.status] || `Error: ${response.status}`;
  return { error: true, message };
}

Helpful Error Messages

Bad

return { error: true, message: 'Error' };
return { error: true, message: 'Failed' };
return { error: true, message: response.status };

Good

return { error: true, message: 'City "Londn" not found. Did you mean "London"?' };
return { error: true, message: 'Weather API rate limit exceeded. Try again in 1 minute.' };
return { error: true, message: 'Invalid API key. Please check your configuration.' };

Error Recovery

When possible, suggest fixes:

if (response.status === 429) {
  return { 
    error: true, 
    message: 'Rate limited. Please wait a moment before trying again.',
    retryAfter: 60,
  };
}

if (response.status === 401) {
  return { 
    error: true, 
    message: 'Session expired. Please reconnect your account.',
    requiresAuth: true,
  };
}

Logging

Use console.log for debugging (output may be limited):

try {
  console.log('Making request to:', url);
  const response = await context.fetch(url);
  console.log('Response status:', response.status);
  // ...
} catch (error) {
  console.error('Request failed:', error.message);
  throw error;
}

Testing Errors

Test your error handling:

1. Missing required parameters
2. Invalid parameter types
3. Missing secrets
4. API returning errors (4xx, 5xx)
5. Network timeouts
6. Invalid JSON responses
7. OAuth not connected