Errors
Tagged error types exposed by the websocket-based bot SDK
The Bot SDK uses specific Effect tagged errors for authentication, gateway delivery, command handling, message APIs, and AI streaming.
Core errors
class AuthenticationError {
readonly _tag = "AuthenticationError"
readonly message: string
readonly cause: unknown
}
class GatewayReadError {
readonly _tag = "GatewayReadError"
readonly message: string
readonly cause: unknown
}
class GatewayDecodeError {
readonly _tag = "GatewayDecodeError"
readonly message: string
readonly payload: string
readonly cause: unknown
}
class GatewaySessionStoreError {
readonly _tag = "GatewaySessionStoreError"
readonly message: string
readonly cause: unknown
}Command and event errors
class CommandArgsDecodeError {
readonly _tag = "CommandArgsDecodeError"
readonly message: string
readonly commandName: string
readonly cause: unknown
}
class CommandHandlerError {
readonly _tag = "CommandHandlerError"
readonly message: string
readonly commandName: string
readonly cause: unknown
}
class CommandSyncError {
readonly _tag = "CommandSyncError"
readonly message: string
readonly cause: unknown
}
class MentionableSyncError {
readonly _tag = "MentionableSyncError"
readonly message: string
readonly cause: unknown
}
class EventHandlerError {
readonly _tag = "EventHandlerError"
readonly message: string
readonly eventType: string
readonly cause: unknown
}Message errors
class MessageSendError {
readonly _tag = "MessageSendError"
readonly message: string
readonly channelId: string
readonly cause: unknown
}
class MessageReplyError {
readonly _tag = "MessageReplyError"
readonly message: string
readonly channelId: string
readonly replyToMessageId: string
readonly cause: unknown
}
class MessageUpdateError {
readonly _tag = "MessageUpdateError"
readonly message: string
readonly messageId: string
readonly cause: unknown
}
class MessageDeleteError {
readonly _tag = "MessageDeleteError"
readonly message: string
readonly messageId: string
readonly cause: unknown
}
class MessageReactError {
readonly _tag = "MessageReactError"
readonly message: string
readonly messageId: string
readonly emoji: string
readonly cause: unknown
}
class MessageListError {
readonly _tag = "MessageListError"
readonly message: string
readonly channelId: string
readonly cause: unknown
}Streaming errors
Streaming and AI helpers may also fail with:
ActorConnectionErrorMessageCreateErrorActorOperationErrorStreamProcessingErrorMessagePersistErrorBotNotConfiguredError
Handling patterns
Catch specific tags when you want tailored recovery:
yield *
bot.start.pipe(
Effect.catchTags({
AuthenticationError: (error) => Effect.logError("Auth failed", { error }),
GatewayReadError: (error) => Effect.logError("Gateway failed", { error }),
}),
)For retry classification, use the exported helpers:
import { getErrorTag, retryPolicyForTag } from "@hazel/bot-sdk"
const tag = getErrorTag(error)
if (tag && retryPolicyForTag(tag) === "transient") {
// retry
}