Salesforce Docs Portal

iOS Error Handling Overview

The Agentforce iOS SDK provides a comprehensive error handling system that manages errors, exceptions, and failure scenarios throughout the conversational AI experience. The system is designed to provide clear error information, graceful degradation, and recovery mechanisms to ensure a robust user experience.

Error Handling Architecture

The error handling system is built around a hierarchical error classification system that provides clear error context and recovery guidance:

Core Error Classes

Error Classification System

The SDK categorizes errors into distinct types for targeted handling and recovery:

SDK Core Errors

The AgentforceSDKError enum provides specific error types for core SDK functionality:

  • defaultAgentNotConfigured: The default agent for the organization has not been configured
  • featureDisabled: Requested feature is disabled via feature flags
  • invalidConversation: The provided conversation instance is invalid or corrupted
  • missingSessionOrViewModel: Required session or view model components are missing
  • noActiveSession: No active conversation session available for operations
  • transcriptGenerationFailed: Server-side transcript generation failed
  • unableToStartASession: Failed to establish a session with the Agentforce service

Data Provider Errors

Data access and processing errors that occur during:

  • Data Retrieval: Failed data fetching from Salesforce
  • Data Processing: Errors during data transformation and validation
  • Data Storage: Issues with local data persistence
  • Data Synchronization: Problems with data sync between local and remote

System Errors

  • Network Errors: Connectivity issues, timeouts, and communication failures
  • Authentication Errors: Credential validation and session management issues
  • Configuration Errors: Invalid configuration settings and missing dependencies
  • Resource Errors: Memory, storage, and system resource limitations

Error Handling Strategies

Error Recovery

The SDK implements multiple recovery strategies:

Automatic Recovery

  • Retry Mechanisms: Automatic retry for transient network errors
  • Fallback Strategies: Alternative approaches when primary methods fail
  • State Restoration: Recovery from corrupted or invalid states
  • Resource Management: Automatic cleanup and resource reallocation

User-Guided Recovery

  • Clear Error Messages: User-friendly error descriptions and guidance
  • Recovery Actions: Suggested actions for error resolution
  • Context Preservation: Maintaining conversation context during recovery
  • Graceful Degradation: Reduced functionality when full recovery isn't possible

Error Reporting

The system provides comprehensive error reporting capabilities:

Error Logging

  • Structured Logging: Consistent error logging format and context
  • Error Categorization: Automatic error classification and tagging
  • Context Preservation: Rich context information for debugging
  • Performance Impact: Minimal performance impact from error logging

Analytics Integration

  • Error Tracking: Integration with analytics systems for error monitoring
  • Trend Analysis: Error pattern analysis and reporting
  • User Impact Assessment: Understanding error impact on user experience
  • Proactive Monitoring: Early detection of error patterns and issues

Implementation Patterns

Basic Error Handling

Implement comprehensive error handling for SDK operations using the specific error types and recovery mechanisms.

Advanced Error Handling

Create custom error handlers that provide specialized error processing and recovery strategies for different error categories.

Error Handling Benefits

  • Robust User Experience: Graceful handling of errors prevents app crashes
  • Clear Error Communication: Users understand what went wrong and how to fix it
  • Developer Debugging: Rich error information for debugging and troubleshooting
  • System Reliability: Automatic recovery mechanisms maintain system stability
  • Performance Monitoring: Error tracking helps identify and resolve performance issues

Best Practices

  • Handle Errors Gracefully: Always implement proper error handling for SDK operations
  • Provide User Feedback: Show clear, actionable error messages to users
  • Implement Recovery: Provide recovery mechanisms where possible
  • Log Errors Appropriately: Use structured logging for debugging and monitoring
  • Test Error Scenarios: Include error handling in your testing strategy

Next Steps