Hazel

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:

  • ActorConnectionError
  • MessageCreateError
  • ActorOperationError
  • StreamProcessingError
  • MessagePersistError
  • BotNotConfiguredError

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
}

On this page