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

# Handle Errors from the Figranium Swift SDK

> FigraniumError is the single error type in the Swift SDK. Learn its fields, SDK-generated codes, and how to branch on status or catch transport and timeout failures.

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

```swift theme={null}
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

```swift Client.swift theme={null}
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

<AccordionGroup>
  <Accordion title="`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.
  </Accordion>

  <Accordion title="`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.                                                             |
  </Accordion>

  <Accordion title="`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.
  </Accordion>

  <Accordion title="`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.
  </Accordion>

  <Accordion title="`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").
  </Accordion>
</AccordionGroup>

## Branching on status

```swift Client.swift theme={null}
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`.

```swift Client.swift theme={null}
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"`.

```swift Client.swift theme={null}
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")`.

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