> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Learn how to handle errors in your Muta placements

Muta will automatically handle errors and prevent the flow from displaying if there are any issues. You can listen for these errors to show appropriate messages to your users.

## Example Usage

```swift theme={null}
import MutaSDK
import SwiftUI

struct OnboardingView: View {
    @State private var errorMessage: String?
    @State private var showError = false
    
    var body: some View {
        VStack {
            // Your content
        }
        .alert("Error", isPresented: $showError) {
            Button("OK", role: .cancel) { }
        } message: {
            Text(errorMessage ?? "An unknown error occurred")
        }
        .onAppear {
            setupErrorHandling()
        }
    }
    
    private func setupErrorHandling() {
        let subscription = Muta.shared.on { event in
            if case .error(let error) = event {
                switch error {
                case .network(let message, _):
                    errorMessage = "Please check your internet connection and try again."
                    showError = true
                    
                case .placement(let message, _, _, _):
                    errorMessage = "Unable to load the onboarding flow. Please try again later."
                    showError = true
                }
            }
        }
        
        // Show the placement
        Muta.shared.displayPlacement(
            placementId: "your-placement-id",
            backgroundColor: .white
        )
    }
}
```

## Error Types

### 1. Network Errors

* Emitted when there's no internet connection
* The flow will not display
* You should show an appropriate "No internet connection" message

### 2. Placement Errors

* Emitted when trying to display a placement that has been deleted
* May indicate an incorrect placement ID or API key
* The flow will not display
* You should show an appropriate error message to the user

## Error Event Structure

### Network Error

```swift theme={null}
case network(message: String, timestamp: Int)
// message: Error message
// timestamp: Unix timestamp in ms
```

### Placement Error

```swift theme={null}
case placement(message: String, code: String, timestamp: Int, placementId: String)
// message: Error message
// code: Error code
// timestamp: Unix timestamp in ms
// placementId: ID of the placement that failed
```

## Best Practices

1. **User-Friendly Messages**: Display error messages that are clear and actionable for users.

2. **Error Recovery**: Implement retry mechanisms for network errors.

3. **Error Logging**: Log errors for debugging and monitoring purposes.

4. **Fallback Content**: Provide fallback content or alternative flows when errors occur.

## Example Implementation

```swift theme={null}
import MutaSDK
import SwiftUI

struct OnboardingView: View {
    @State private var errorMessage: String?
    @State private var showError = false
    @State private var showRetry = false
    
    var body: some View {
        VStack {
            // Your content
        }
        .alert("Error", isPresented: $showError) {
            if showRetry {
                Button("Retry") {
                    retryPlacement()
                }
            }
            Button("OK", role: .cancel) { }
        } message: {
            Text(errorMessage ?? "An unknown error occurred")
        }
        .onAppear {
            setupErrorHandling()
        }
    }
    
    private func setupErrorHandling() {
        let subscription = Muta.shared.on { event in
            if case .error(let error) = event {
                switch error {
                case .network(let message, _):
                    errorMessage = "Please check your internet connection and try again."
                    showError = true
                    showRetry = true
                    
                case .placement(let message, _, _, _):
                    errorMessage = "Unable to load the onboarding flow. Please try again later."
                    showError = true
                    showRetry = false
                }
            }
        }
        
        // Show the placement
        Muta.shared.displayPlacement(
            placementId: "your-placement-id",
            backgroundColor: .white
        )
    }
    
    private func retryPlacement() {
        Muta.shared.displayPlacement(
            placementId: "your-placement-id",
            backgroundColor: .white
        )
    }
}
```

## Error Codes

### Network Errors

* `NETWORK_ERROR`: General network connectivity issues
* `TIMEOUT_ERROR`: Request timeout
* `OFFLINE_ERROR`: Device is offline

### Placement Errors

* `INVALID_PLACEMENT_ID`: The provided placement ID is invalid or doesn't exist
* `INVALID_API_KEY`: The API key is invalid or has been revoked
* `PLACEMENT_NOT_FOUND`: The placement could not be found
* `PLACEMENT_DISABLED`: The placement has been disabled
* `PLACEMENT_EXPIRED`: The placement has expired