> ## Documentation Index > Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt > Use this file to discover all available pages before exploring further. # Error Handling > Exception hierarchy and error handling patterns for the Chatbase Android SDK. ## 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. ```kotlin theme={null} class ApiException( val httpStatus: Int, val errorCode: String, val errorMessage: String, val details: Map? = null ) : ChatbaseException ``` The HTTP status code of the error response (e.g. `401`, `403`, `429`). Machine-readable error code. Use this for programmatic handling. Human-readable error description. Optional field-level validation errors. ### Convenience Properties ```kotlin theme={null} 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` ```kotlin theme={null} 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 Use a try-catch block with the SDK's exception hierarchy: ```kotlin theme={null} 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: ```kotlin theme={null} 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: ```kotlin theme={null} 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 -> {} } } ``` ## Related Streaming callbacks and error events SDK setup and configuration