Error Handling

Exception Hierarchy

All SDK errors extend ChatbaseException:

ChatbaseException
├── ApiException        — API errors from the Chatbase server
└── NetworkException    — Connection failures, DNS errors, timeouts

ApiException

class ApiException : ChatbaseException — Package: com.chatbase.sdk.exception Thrown when the Chatbase API returns an error response.

class ApiException(
    val httpStatus: Int,
    val errorCode: String,
    val errorMessage: String,
    val details: Map<String, String>? = null
) : ChatbaseException

Int

required

The HTTP status code of the error response (e.g. 401, 403, 429).

String

required

Machine-readable error code. Use this for programmatic handling.

String

required

Human-readable error description.

Map<String, String>?

Optional field-level validation errors.

Convenience Properties

val isRateLimited: Boolean      // httpStatus == 429
val isNotFound: Boolean         // httpStatus == 404
val isCreditsExhausted: Boolean // httpStatus == 402

For statuses without a helper — such as 401 (authentication) or 403 (access denied) — check httpStatus or errorCode directly.

Error Codes

These are the error codes you may encounter through ApiException.errorCode:

Status	Code	Description
400	`VALIDATION_INVALID_BODY`	The request body failed validation. `details` maps field names to messages. Also returned when a tool result exceeds the 20 KB limit.
400	`CHAT_RETRY_NO_USER_MESSAGE`	The message passed to `retry()` has no preceding user message to retry from.
401	`AUTH_INVALID_JWT`	The JWT token passed to `identify()` is invalid, expired, or could not be verified — including when identity verification is not configured for the agent. See User Identity.
402	`CHAT_CREDITS_EXHAUSTED`	The workspace’s message credit balance is zero. Upgrade the plan or wait for credits to reset. Caught by `isCreditsExhausted`.
402	`CHAT_AGENT_CREDITS_EXHAUSTED`	The specific agent’s credit allocation has been used up. Caught by `isCreditsExhausted`.
403	`AUTH_OWNERSHIP_MISMATCH`	The conversation belongs to a different user or device. Also returned by `retry()` and `listMessages()` when the conversation does not exist.
403	`CHAT_CONVERSATION_MISMATCH`	The conversation could not be resolved for this agent.
403	`CHAT_MODEL_NOT_ALLOWED`	The agent uses a model not available on the current plan.
403	`CHAT_CONVERSATION_NOT_ONGOING`	The conversation has ended or was taken over and cannot receive new messages. Start a new conversation.
404	`AGENT_NOT_FOUND`	No agent matches the provided ID, or the Android SDK channel is not enabled for the agent (see Quick Start). Caught by `isNotFound`.
404	`RESOURCE_NOT_FOUND`	The conversation or message does not exist. Caught by `isNotFound`.
404	`CHAT_RETRY_MESSAGE_NOT_FOUND`	The message ID provided for `retry()` was not found. Caught by `isNotFound`.
404	`RESOURCE_TOOL_CALL_NOT_FOUND`	The tool call was not found or has expired. Can surface through the automatic tool loop. Caught by `isNotFound`.
404	`RESOURCE_TOOL_CALL_MISMATCH`	The tool call does not belong to this conversation. Caught by `isNotFound`.
404	`RESOURCE_TOOL_RESULT_NOT_PENDING`	No pending tool result exists for this tool call — usually a duplicate submission. Caught by `isNotFound`.
429	`RATE_LIMIT_TOO_MANY_REQUESTS`	Rate limit exceeded (1,000 requests per 10 seconds per device). Back off and retry. Caught by `isRateLimited`.
500	`CHAT_STREAMING_ERROR`	The response stream failed server-side. Safe to retry.
500	`INTERNAL_SERVER_ERROR`	An unexpected server error occurred. Retry, or contact support if it persists.

NetworkException

class NetworkException : ChatbaseException — Package: com.chatbase.sdk.exception

class NetworkException(
    message: String,
    cause: Throwable? = null
) : ChatbaseException

Thrown for connection-level failures — DNS errors, socket timeouts, no internet connectivity, and similar issues.

Handling Errors

Suspend Functions
Streaming Callbacks
Flow

Use a try-catch block with the SDK’s exception hierarchy:

try {
    val response = client.sendMessage("Hello")
} catch (e: ApiException) {
    when {
        e.httpStatus == 401 -> {
            println("Authentication failed. Check your JWT token.")
        }
        e.httpStatus == 403 -> {
            println("Access denied. Check conversation ownership or plan.")
        }
        e.isRateLimited -> {
            println("Rate limited. Back off and retry.")
        }
        e.isCreditsExhausted -> {
            println("No credits remaining. Upgrade plan.")
        }
        e.isNotFound -> {
            println("Not found. Check your agent ID.")
        }
        else -> {
            println("API error: ${e.errorCode} — ${e.errorMessage}")
        }
    }
} catch (e: NetworkException) {
    println("Network error: ${e.message}")
} catch (e: ChatbaseException) {
    println("Unknown SDK error: ${e.message}")
}

Handle errors via the onError callback:

client.sendMessage("Hello") {
    onTextDelta { delta -> print(delta) }
    onError { error ->
        when (error) {
            is ApiException -> println("API error: ${error.errorCode}")
            is NetworkException -> println("Network error: ${error.message}")
            else -> println("Error: ${error.message}")
        }
    }
}

Check for ChatStreamEvent.Error events:

client.sendMessageStream("Hello").collect { event ->
    when (event) {
        is ChatStreamEvent.TextDelta -> print(event.delta)
        is ChatStreamEvent.Error -> {
            when (val ex = event.exception) {
                is ApiException -> println("${ex.errorCode}: ${ex.errorMessage}")
                is NetworkException -> println("Network: ${ex.message}")
                else -> println("Error: ${ex.message}")
            }
        }
        else -> {}
    }
}

Streaming

Streaming callbacks and error events

Overview

SDK setup and configuration

Getting Started

Reference

Exception Hierarchy

ApiException

Convenience Properties

Error Codes

NetworkException

Handling Errors

Streaming

Overview

​Exception Hierarchy

​ApiException

​Convenience Properties

​Error Codes

​NetworkException

​Handling Errors

​Related

Streaming

Overview

Exception Hierarchy

ApiException

Convenience Properties

Error Codes

NetworkException

Handling Errors

Related