BlazeSDK provides structured and consistent error information through the BlazeError type. Errors can be delivered globally via the SDK delegate, locally via method completion handlers, or via source delegates for widgets, entryPoints, etc., depending on the context.

Error Structure

public struct BlazeError: Error, Equatable {
    public let domain: ErrorDomain
    public let errorMessage: String  
    public let statusCode: Int
    public let metadata: [String: String]
    public let underlyingError: Error?
}

• domain: Categorizes the error (e.g., .initialization, .widget, etc.)
• errorMessage: Human-readable description of the issue
• statusCode: Unique numeric identifier for the error
• metadata: Optional contextual info (e.g., data source type)
• underlyingError: The low-level error that caused this issue, if available

✅ You can inspect underlyingError to access the original system or network error (e.g., decoding failure, URL error).

Error Delivery Mechanisms

1. BlazeSDKDelegate

Errors marked as 'Thrown to Global Delegate' in the table below are automatically forwarded to your BlazeSDKDelegate implementation via the onErrorThrown callback.

// Example of handling error via BlazeSDKDelegate
private func createBlazeSDKGlobalDelegate() -> BlazeSDKDelegate {
    return BlazeSDKDelegate { [weak self] eventData in
        self?.onEventTriggered(eventData: eventData)
    } onErrorThrown: { [weak self] error in
        self?.onErrorThrown(error)
    }
}

func onErrorThrown(_ error: BlazeError) {
    // Handle specific error domains and reasons
    switch error.domain {
    case .initialization(let reason):
        handleInitializationError(reason)
    case .widget(let reason):
        handleWidgetError(reason)
    default:
        break
    }
}

Blaze.shared.delegate = createBlazeSDKGlobalDelegate()

2. Completion Handlers

Some errors are returned only through completion handlers for specific API calls (e.g., initialization, setting user ID, universal link processing). Therefore, in these cases, you should handle errors exclusively in the callback, as this is the only way to properly catch and respond to them.

// Error should be handled via completion block
Blaze.shared.initialize(
    apiKey: "your-api-key",
    externalUserId: "user123"
) { result in
    switch result {
    case .success:
        break

      case .failure(let error):
        // Handle specific error domains and reasons
        if case .initialization(let reason) = error.domain {
            switch reason {
            case .invalidApiKey:
                print("Invalid API key")
            case .alreadyInitialized:
                print("SDK is already initialized")
            default:
                break
            }
        }
    }
}

3. Source Delegates

Component-specific errors are delivered via source delegate onDataLoadComplete handlers for widgets, containers, and entry points:

• BlazeWidgetDelegate → Widget load errors via onDataLoadComplete handler
• BlazePlayerContainerDelegate → Container load errors via onDataLoadComplete handler
• BlazeInlinePlayerDelegate → Inline player load errors via onDataLoadComplete handler
• BlazePlayerEntryPointDelegate → Entry point load errors via onDataLoadComplete handler

// Example of handling error via widget delegate
widget.delegate = BlazeWidgetDelegate { [weak self] eventData in
    self?.onEventTriggered(eventData: eventData)
} onDataLoadComplete: { [weak self] result in
    switch result {
    case .success:
        break
    case .failure(let error):
        self?.handleWidgetError(error)
    }
}

Notes

• ✅ All errors marked with ✅ Yes are forwarded to the global delegate.
• ⚠️ Some internal SDK issues are exposed via .general with unexpected reason to simplify surface-level error handling.
• 🛠 If needed, use underlyingError for deeper debugging or analytics.

Error Codes

General Errors (1000–1099)

Initialization Errors (1100–1199)

These errors are delivered via theBlaze.shared.initialize() completion handler.

Content Preparation Errors (1200–1299)

These errors are delivered viaprepareStories/prepareMoments/prepareVideos() completion handlers.

Widget Errors (1300–1399)

These errors are delivered via widget completion handlers and delegates.

Entry Point Errors (1400–1499)

These errors are delivered viaplayStories/playMoments/playVideos() completion handlers.

User Management Errors (1500–1599)

These errors are delivered viasetExternalUserId() completion handlers.

Universal Link Errors (1600–1699)

These errors are delivered viahandleUniversalLink() completion handlers.

Notification Extra Info Errors (1700–1799)

These errors are delivered via notification handling completion handlers.

Data Source Errors (1900–1999)

These errors occur during internal data source operations.

Content Errors (2000–2099)

These errors occur during internal content operations.

Asset Errors (2100–2199)

These errors occur during asset loading operations.

Storage Errors (2200–2299)

These errors occur during internal storage operations.

Playback Errors (2400–2499)

These errors occur during media playback operations.

Image Loading Errors (2500–2599)

These errors occur during image loading operations.

Sharing Errors (2600–2699)

These errors occur during content sharing operations.

Direct Media Errors (2700–2799)

These errors are delivered via play method completion handlers when feature is active.

Playback Configuration Errors (2800–2899)

These errors occur during playback configuration operations.