Error Handling

Every throwing SDK call throws SDKException. There is no SDKError type.

do {
    let result = try await RunAnywhere.generate(prompt: "Hello")
    print(result.text)
} catch let error as SDKException {
    print(error.code)               // RAErrorCode
    print(error.category)           // RAErrorCategory
    print(error.message)            // String
    print(error.errorDescription ?? "")
} catch {
    print("Unexpected: \(error)")
}

SDKException

SDKException is a struct wrapping a proto RASDKError. It conforms to Error, LocalizedError, Sendable, CustomStringConvertible, Equatable, and Hashable.

Member	Type	Notes
`code`	`RAErrorCode`	Proto enum. Has an `UNRECOGNIZED(Int)` case.
`category`	`RAErrorCategory`	Coarse bucket. Branch on this first.
`message`	`String`	Human-readable summary.
`fieldPath`	`String?`	Set on validation failures.
`errorDescription`	`String?`	`LocalizedError`. Safe to show to users.
`failureReason`	`String?`	`LocalizedError`.
`recoverySuggestion`	`String?`	`LocalizedError`. Non-nil for a subset of codes.
`proto`	`RASDKError`	The full wire envelope.
`underlying`	`(any Error)?`	Wrapped cause, when there is one.
`stackTrace`	`[String]`	Captured at construction.
`telemetryProperties`	`[String: String]`	Flattened for logging.

Branch on category first

RAErrorCategory has a small, stable set of values. RAErrorCode has hundreds. Handle the category, then drill into specific codes only where you can do something different.

catch let error as SDKException {
    switch error.category {
    case .network:
        showRetry(error)
    case .validation:
        highlightField(error.fieldPath, message: error.message)
    case .model:
        promptToDownloadModel()
    case .io:
        showStorageFullDialog()
    case .auth:
        reauthenticate()
    case .configuration, .component, .internal, .unspecified:
        showGeneric(error)
    case .UNRECOGNIZED:
        showGeneric(error)
    }
}

RAErrorCategory cases: .unspecified, .network, .validation, .model, .component, .io, .auth, .`internal`, .configuration. Note the backticks: internal is a Swift keyword.

Codes worth handling individually

RAErrorCode is generated from the proto, so a switch must be exhaustive: include default or handle .UNRECOGNIZED.

switch error.code {
case .notInitialized:      try RunAnywhere.initialize(environment: .development)
case .modelNotFound:       await downloadModel()
case .modelNotLoaded:      await loadModel()
case .insufficientMemory:  await unloadUnusedModels()
case .insufficientStorage: showStorageCleanup()
case .contextTooLong:      trimConversationHistory()
case .generationCancelled: break          // user action, not a failure
case .networkUnavailable:  showOfflineBanner()
case .timeout:             retry()
case .invalidApiKey:       showCredentialsScreen()
default:                   showGeneric(error)
}

Codes are grouped by numeric range: 100 to 106 initialization and configuration, 110 to 116 model, 130 to 136 generation, 150 to 161 network, 180 to 193 storage, 220 to 221 hardware, 230 to 236 component state, 250+ validation.

The case is .invalidApiKey, not .invalidAPIKey. Swift protobuf lowercases the acronym.

Cancellation is not a failure

.cancelled and .streamCancelled arrive when the caller cancelled. isExpected on RAErrorCode marks exactly those two so you can suppress logging. .generationCancelled (code 136) is a distinct code and is not covered by isExpected.

guard !error.code.isExpected else { return }
error.log()

Validation errors

Validation failures carry the offending field on fieldPath.

catch let error as SDKException where error.category == .validation {
    if let path = error.fieldPath {
        form.markInvalid(path, reason: error.message)
    }
}

Constructing exceptions

You rarely need to, but the factories exist for wrapping your own failures on the same shape:

SDKException.modelNotFound("smollm2-360m-q8_0")
SDKException.notInitialized("TTS voice not loaded")
SDKException.invalidConfiguration("baseURL is required in production")
SDKException.validationFailed(fieldPath: "options.maxTokens", message: "must be > 0")
SDKException.cancelled()
SDKException.notImplemented("diffusion on this platform")
SDKException.timeout("model download")
SDKException.networkError("connection reset")

Or build one directly:

SDKException(code: .generationFailed, message: "Backend returned no tokens", category: .component)

To normalize an arbitrary Error:

let sdkError = SDKException.from(someError, category: .internal)

SwiftUI

struct ContentView: View {
    @State private var error: SDKException?

    var body: some View {
        MainView()
            .alert(
                "Something went wrong",
                isPresented: .constant(error != nil),
                presenting: error
            ) { failure in
                if failure.code == .modelNotFound {
                    Button("Download") { Task { await downloadModel() } }
                }
                Button("OK", role: .cancel) { error = nil }
            } message: { failure in
                Text(failure.recoverySuggestion ?? failure.message)
            }
    }
}

Non-throwing entry points

Not every failure arrives as a thrown exception. loadModel and unloadModel return a result with a success flag instead:

var request = RAModelLoadRequest()
request.modelID = modelId
request.category = .language

let result = await RunAnywhere.loadModel(request)
guard result.success else {
    throw SDKException(code: .modelLoadFailed, message: result.errorMessage, category: .model)
}

listModels, queryModels, getModel, and getStorageInfo follow the same pattern.

Errors on the event bus

Errors emitted from background work reach RunAnywhere.events. Subscribe to the error category rather than filtering the full stream.

import Combine

var cancellables = Set<AnyCancellable>()

RunAnywhere.events.errorEvents
    .receive(on: DispatchQueue.main)
    .sink { event in
        logger.error("SDK event: \(event.category)")
    }
    .store(in: &cancellables)

RASDKEvent has no .type property. The discriminants are .category (RAEventCategory) and the .event oneof payload.

Getting Started

Swift SDK

Kotlin SDK

React Native SDK

Flutter SDK

Web SDK

Vibe Coding

SDKException

Branch on category first

Codes worth handling individually

Cancellation is not a failure

Validation errors

Constructing exceptions

SwiftUI

Non-throwing entry points

Errors on the event bus

​SDKException

​Branch on category first

​Codes worth handling individually

​Cancellation is not a failure

​Validation errors

​Constructing exceptions

​SwiftUI

​Non-throwing entry points

​Errors on the event bus

SDKException

Branch on category first

Codes worth handling individually

Cancellation is not a failure

Validation errors

Constructing exceptions

SwiftUI

Non-throwing entry points

Errors on the event bus