Hazel

Errors

Specific tagged error types and handling in the Bot SDK

The Bot SDK uses specific Effect tagged errors for each operation.

Core Errors

Authentication

class AuthenticationError {
	readonly _tag = "AuthenticationError"
	readonly message: string
	readonly cause: unknown
}

Startup

class ShapeStreamStartupError {
	readonly _tag = "ShapeStreamStartupError"
	readonly message: string
	readonly cause: unknown
}

class EventDispatcherStartupError {
	readonly _tag = "EventDispatcherStartupError"
	readonly message: string
	readonly cause: unknown
}

Queue Errors

class QueueCreateError {
	readonly _tag = "QueueCreateError"
	readonly message: string
	readonly eventType: string
	readonly cause: unknown
}

class QueueOfferError {
	readonly _tag = "QueueOfferError"
	readonly message: string
	readonly eventType: string
	readonly cause: unknown
}

class QueueTakeError {
	readonly _tag = "QueueTakeError"
	readonly message: string
	readonly eventType: string
	readonly cause: unknown
}

class QueuePollError {
	readonly _tag = "QueuePollError"
	readonly message: string
	readonly eventType: string
	readonly cause: unknown
}

class QueueSizeError {
	readonly _tag = "QueueSizeError"
	readonly message: string
	readonly eventType: string
	readonly cause: unknown
}

Shape Stream Errors

class ShapeStreamCreateError {
	readonly _tag = "ShapeStreamCreateError"
	readonly message: string
	readonly table: string
	readonly cause: unknown
}

class ShapeStreamSubscribeError {
	readonly _tag = "ShapeStreamSubscribeError"
	readonly message: string
	readonly table: string
	readonly cause: unknown
}

class ShapeStreamDecodeError {
	readonly _tag = "ShapeStreamDecodeError"
	readonly message: string
	readonly table: string
	readonly cause: unknown
}

Command and Message 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 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
}

Dispatch Errors

class EventDispatchError {
	readonly _tag = "EventDispatchError"
	readonly message: string
	readonly eventType: string
	readonly cause: unknown
}

class HandlerRetryExhaustedError {
	readonly _tag = "HandlerRetryExhaustedError"
	readonly message: string
	readonly eventType: string
	readonly cause: unknown
}

class EventHandlerError {
	readonly _tag = "EventHandlerError"
	readonly message: string
	readonly eventType: string
	readonly cause: unknown
}

SSE Errors

class SseRequestError {
	readonly _tag = "SseRequestError"
	readonly message: string
	readonly cause: unknown
}

class SseResponseError {
	readonly _tag = "SseResponseError"
	readonly message: string
	readonly status?: number
	readonly cause?: unknown
}

class SsePayloadParseError {
	readonly _tag = "SsePayloadParseError"
	readonly message: string
	readonly payload: string
	readonly cause: unknown
}

class SseCommandDecodeError {
	readonly _tag = "SseCommandDecodeError"
	readonly message: string
	readonly payload: string
	readonly cause: unknown
}

class SseReconnectExhaustedError {
	readonly _tag = "SseReconnectExhaustedError"
	readonly message: string
	readonly retryCycle: number
	readonly cause: unknown
}

class SseUnexpectedError {
	readonly _tag = "SseUnexpectedError"
	readonly message: string
	readonly cause: unknown
}

Streaming Errors

These are specific to AI streaming:

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

Handling Patterns

Catch specific tags

yield *
	bot.message.send(channelId, content).pipe(
		Effect.catchTags({
			MessageSendError: (error) => Effect.logError("Send failed", { error }),
			MessageReplyError: (error) => Effect.logError("Reply failed", { error }),
		}),
	)

Handle command failures explicitly

yield *
	myCommandEffect.pipe(
		Effect.catchTag("CommandArgsDecodeError", (error) =>
			Effect.logWarning("Invalid command arguments", { error }),
		),
		Effect.catchTag("CommandHandlerError", (error) =>
			Effect.logError("Command execution failed", { error }),
		),
	)

Retry Classification

Retry behavior is tag-based.

import { getErrorTag, retryPolicyForTag } from "@hazel/bot-sdk"

const tag = getErrorTag(error)
if (tag) {
	const policy = retryPolicyForTag(tag)
	// "none" | "quick" | "transient" | "connection"
}

On this page