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:
ActorConnectionErrorMessageCreateErrorActorOperationErrorStreamProcessingErrorMessagePersistErrorBotNotConfiguredError
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"
}