Error Handling

The Two Error Types

The SDK throws two kinds of error. Both give you a readable localizedDescription.

Type	Covers
`APIError`	Network problems and error responses from the Chatbase server.
`ChatError`	Problems the SDK finds on its own, before or instead of a server reply.

Swift errors are not arranged in a hierarchy, so there is no single type that catches both. Match each one, and keep a final catch for anything else, such as a CancellationError or an error from your own tool handler.

APIError

public enum APIError: Error, LocalizedError {
    case invalidResponse
    case httpError(statusCode: Int, detail: APIErrorDetail)
    case networkError(Error)
}

case

The server sent something that was not an HTTP response. Rare. Treat it like a network problem.

case

The server returned an error status. detail holds the code you can check in your app.

case

The request never got through: no connection, DNS failure, or a timeout. The value inside is the underlying URLError.

Shortcuts

public var statusCode: Int?   // nil unless it is .httpError
public var apiCode: String?   // the server's error code, nil unless it is .httpError

catch let error as APIError {
    switch error.statusCode {
    case 401: promptSignIn()
    case 402: showUpgradePrompt()
    case 429: backOffAndRetry()
    default:  showGenericError()
    }
}

APIErrorDetail

public struct APIErrorDetail: Decodable, Sendable {
    public let code: String
    public let message: String
    public let details: [String: String]?
}

String

required

The error code. Check this in your app, never the message.

String

required

A description written for developers.

[String: String]?

Which fields were wrong, when the server tells you.

message is written for developers. It is not translated and not meant for your users. Turn code into your own wording instead of showing localizedDescription on screen.

If the error body cannot be read, the SDK still throws .httpError with code set to "UNKNOWN", so you never lose the status code.

ChatError

public enum ChatError: Error, LocalizedError {
    case noContent
    case decodingFailed(String)
    case invalidURL(String)
    case toolLoopLimitExceeded(limit: Int)
}

Case	What happened	What to do
`.noContent`	The agent asked for a tool before there was a conversation to attach the result to.	Send the message again.
`.decodingFailed(String)`	A reply did not look the way the SDK expected.	Update to the latest SDK version. If it keeps happening, contact support.
`.invalidURL(String)`	The client was created with a `baseURL` that is not a valid URL.	Leave `baseURL` at its default. Every request fails until you do.
`.toolLoopLimitExceeded(limit:)`	The agent asked for more tool rounds than `maxToolLoopSteps` allows.	See Client-Side Tools.

catch ChatError.toolLoopLimitExceeded(let limit) {
    print("Stopped after \(limit) tool steps")
}

Error Codes

These are the codes you can get from APIError.apiCode:

Status	Code	Description
400	`VALIDATION_INVALID_BODY`	The request was not valid. `details` says which fields were wrong. You also get this when a tool result is over 20 KB.
400	`VALIDATION_INVALID_JSON`	The request body was not valid JSON.
400	`VALIDATION_MISSING_USER_IDENTIFIER`	The device ID header was missing. You should not see this, since the SDK always sends it.
400	`AUTH_INVALID_USER_AGENT`	The SDK’s `User-Agent` header was missing or not recognized. You should only see this if something rewrites your headers.
400	`CHAT_RETRY_NO_USER_MESSAGE`	The message you passed to `retry()` has no user message before it to answer.
401	`AUTH_INVALID_JWT`	The token you passed to `identify()`, or the saved token on a later request, is invalid or expired. You also get this when identity verification is not set up for the agent. See User Identity.
402	`CHAT_CREDITS_EXHAUSTED`	The workspace has no message credits left. Upgrade the plan or wait for credits to reset.
402	`CHAT_AGENT_CREDITS_EXHAUSTED`	This agent has used up its share of credits.
403	`AUTH_OWNERSHIP_MISMATCH`	The conversation belongs to a different user or device. `retry()` and `listMessages()` also return this when the conversation does not exist.
403	`CHAT_CONVERSATION_MISMATCH`	The conversation does not belong to this agent.
403	`CHAT_MODEL_NOT_ALLOWED`	The agent uses a model that the current plan does not include.
403	`CHAT_CONVERSATION_NOT_ONGOING`	The conversation has ended, or a person took it over, so it cannot take new messages. Start a new one.
404	`AGENT_NOT_FOUND`	No agent has that ID, or the iOS SDK channel is turned off for the agent. See Quick Start.
404	`RESOURCE_NOT_FOUND`	The conversation or message does not exist.
404	`CHAT_RETRY_MESSAGE_NOT_FOUND`	The message ID you gave `retry()` was not found.
404	`RESOURCE_TOOL_CALL_NOT_FOUND`	The tool call was not found, or it expired. This can come up during the tool loop.
404	`RESOURCE_TOOL_CALL_MISMATCH`	The tool call belongs to a different conversation.
404	`RESOURCE_TOOL_RESULT_NOT_PENDING`	The server was not waiting for this tool result. Usually it was sent twice.
429	`RATE_LIMIT_TOO_MANY_REQUESTS`	Too many requests (the limit is 1,000 every 10 seconds per device). Wait and try again. The response includes a `Retry-After` header.
500	`CHAT_STREAMING_ERROR`	The reply failed on the server. Safe to try again.
500	`INTERNAL_SERVER_ERROR`	Something went wrong on the server. Try again, or contact support if it keeps happening.

AGENT_NOT_FOUND looks the same whether the agent does not exist or the iOS SDK channel is turned off. If you are sure the agent ID is right, check Deploy → iOS SDK first.

Handling Errors

async/await
Network problems
SwiftUI state
Rate limits

do {
    let response = try await client.send("Hello", conversationId: conversationId)
    render(response)

} catch let error as APIError {
    switch (error.statusCode, error.apiCode) {
    case (401, _):
        try await refreshIdentity()
    case (402, _):
        show("You're out of message credits.")
    case (403, "CHAT_CONVERSATION_NOT_ONGOING"):
        startNewConversation()
    case (404, "AGENT_NOT_FOUND"):
        assertionFailure("Check the agent ID and that the iOS SDK channel is on")
    case (429, _):
        await backOff()
    default:
        show("Something went wrong. Please try again.")
    }

} catch let error as ChatError {
    switch error {
    case .toolLoopLimitExceeded:
        show("That took too many steps. Try rewording it.")
    default:
        show("Something went wrong. Please try again.")
    }

} catch is CancellationError {
    // The user stopped it. Nothing to show.

} catch {
    show("Something went wrong. Please try again.")
}

Connection problems come back as .networkError, wrapping a URLError:

catch let error as APIError {
    if case .networkError(let underlying) = error {
        switch (underlying as? URLError)?.code {
        case .notConnectedToInternet, .networkConnectionLost:
            show("You appear to be offline.")
        case .timedOut:
            show("The request timed out. Try again.")
        default:
            show("Couldn't reach Chatbase.")
        }
    }
}

Change timeouts with the URLSessionConfiguration you pass to ChatbaseClient. See Overview.

ConversationState and ConversationListState never throw. Errors go into error:

.alert(
    "Something went wrong",
    isPresented: .init(
        get: { state.error != nil },
        set: { if !$0 { state.clearError() } }
    )
) {
    Button("OK") { state.clearError() }
} message: {
    Text(userFacingMessage(for: state.error))
}

The failed bubble is also marked isError, so you can show a retry button in the list instead of an alert. See SwiftUI.

Wait before trying again, and make each wait longer than the last:

func withRetry<T>(
    attempts: Int = 3,
    _ operation: () async throws -> T
) async throws -> T {
    var delay: Duration = .milliseconds(500)
    for attempt in 1...attempts {
        do {
            return try await operation()
        } catch let error as APIError where error.statusCode == 429 && attempt < attempts {
            try await Task.sleep(for: delay + .milliseconds(.random(in: 0...200)))
            delay *= 2
        }
    }
    throw APIError.invalidResponse
}

The small random amount keeps many devices from retrying at the same moment.

Tool results are already retried inside the SDK, 3 times with a growing wait. Do not add your own retry around tool handlers.

Errors Inside Tool Handlers

An error thrown by a tool handler does not come out of send. The SDK turns it into {"error": "..."} and gives it to the agent, so the agent can recover. See When a Tool Fails. CancellationError is the exception. It is passed through, so cancelling the Task cancels the reply.

What to Report

The SDK already logs each request and response under com.chatbase.sdk. See Logging. When you report a problem, include the apiCode, the statusCode, and the time. That is enough to find the request on the server.

Do not send tokens or message text to a crash reporting service. APIError.localizedDescription is safe. It contains only the code, the message, and the status.

Streaming

Where most errors show up

User Identity

Handling expired and rejected tokens

Client-Side Tools

Reporting failures back to the agent

Overview

Setup and configuration

Getting Started

Reference

The Two Error Types

APIError

Shortcuts

APIErrorDetail

ChatError

Error Codes

Handling Errors

Errors Inside Tool Handlers

What to Report

Streaming

User Identity

Client-Side Tools

Overview

​The Two Error Types

​APIError

​Shortcuts

​APIErrorDetail

​ChatError

​Error Codes

​Handling Errors

​Errors Inside Tool Handlers

​What to Report

​Related

Streaming

User Identity

Client-Side Tools

Overview

The Two Error Types

APIError

Shortcuts

APIErrorDetail

ChatError

Error Codes

Handling Errors

Errors Inside Tool Handlers

What to Report

Related