Handle Errors from the Figranium Swift SDK

The Figranium Swift SDK raises one error type for every failure: FigraniumError. It covers HTTP error responses, network failures, timeouts, and request aborts. You can branch on error.status for HTTP semantics, on error.code for machine-readable categories, and on error.errorDescription for a human-readable message.

FigraniumError shape

public struct FigraniumError: Error, Sendable, LocalizedError {
    public var message: String
    public var status: Int
    public var code: String?
    public var details: JSONValue?
    public var requestID: String?
    public var errorDescription: String? { message }
}

FigraniumError conforms to LocalizedError, so error.errorDescription returns message and integrates with SwiftUI and NSError bridging.

Basic handling

Client.swift

import Figranium

let client = Figranium(apiKey: "your-api-key")

do {
    try await client.runTask("missing-task")
} catch let error as FigraniumError {
    print(error.status)      // e.g. 404
    print(error.code)        // e.g. "TASK_NOT_FOUND"
    print(error.details)     // server diagnostics
    print(error.requestID)   // when supplied by the server or proxy
}

Fields

status

The HTTP status returned by the Figranium server, if a response arrived. 0 when the request never reached a status, such as a network failure, DNS error, or cancelled request.

code

Server-provided machine-readable error code, taken from the response body’s error field. Also used for SDK-generated conditions:

Code	Meaning
`NETWORK_ERROR`	The request could not reach the server, or a non-Figranium error occurred during the request (including JSON decoding failures).
`REQUEST_ABORTED`	The request was aborted by a timeout or cancellation.
`EMPTY_RESPONSE`	The response body was empty or the server returned 204.
`INTENT_NOT_CONFIGURED`	`FigraniumIntentConfiguration` was not configured before invoking an App Intent.
`TASK_NOT_ALLOWED`	A Foundation Models tool tried to run a task not in the allowed set.

details

Free-form value from the response body’s details or detail field. Typically an object describing which validation failed, which record was missing, or which field was invalid.

requestID

Value of the x-request-id response header, when the server or a proxy sets one. Include this in bug reports to make server-side logs easier to correlate.

message

Human-readable description of what went wrong. For server errors, this is taken from the response body’s message or error field. For SDK-generated errors, it describes the condition (for example, “Figranium request was cancelled”).

Branching on status

Client.swift

do {
    try await client.tasks.get("some-task-id")
} catch let error as FigraniumError {
    switch error.status {
    case 401:
        // Reauthenticate or refresh the API key.
        refreshAPIKey()
    case 404:
        // Task is gone; treat as an empty result.
        return nil
    case 429:
        // Back off and retry.
        try await Task.sleep(for: .seconds(2))
    default:
        throw error
    }
}

Transport failures

When the request never gets a response (server unreachable, DNS failure, TLS error), status is 0 and code is NETWORK_ERROR.

Client.swift

do {
    try await client.health.check()
} catch let error as FigraniumError {
    if error.code == "NETWORK_ERROR" {
        print("Figranium is unreachable")
    }
}

Timeouts and cancellation

When a request exceeds the configured timeout, or when the calling Task is cancelled, the SDK raises FigraniumError with code: "REQUEST_ABORTED".

Client.swift

do {
    try await client.runTask("slow-task", options: .init(timeout: 5))
} catch let error as FigraniumError {
    if error.code == "REQUEST_ABORTED" {
        print("The request timed out or was cancelled")
    }
}

Cancelling the consuming Task of a stream also aborts the underlying network request and raises FigraniumError(code: "REQUEST_ABORTED").

Always check error is FigraniumError before reading SDK-specific fields. Unknown errors should be rethrown so they bubble up to your global error handler.

JavaScript SDK

Python SDK

Swift SDK

Handle Errors from the Figranium Swift SDK

FigraniumError shape

Basic handling

Fields

Branching on status

Transport failures

Timeouts and cancellation

​FigraniumError shape

​Basic handling

​Fields

​Branching on status

​Transport failures

​Timeouts and cancellation

FigraniumError shape

Basic handling

Fields

Branching on status

Transport failures

Timeouts and cancellation