Handling Errors and Exceptions in alterself Selfbots

Every error that alterself raises derives from a single base class, AlterselfError, so you can always write a broad catch at the top of your stack and narrow it down as needed. Understanding the exception hierarchy lets you write targeted handlers that recover gracefully from transient failures, surface useful diagnostics for permanent ones, and avoid silently swallowing errors that require your attention.

Exception Hierarchy

AlterselfError
├── HTTPError              - HTTP request failed (4xx, 5xx)
├── GatewayError           - WebSocket-level failure
│   └── SessionClosed      - Gateway connection closed
├── CommandError           - Command pipeline failure
│   ├── CheckFailed        - A check decorator returned falsy
│   ├── ConversionFailed   - Type converter raised an exception
│   ├── CommandNotFound    - No command matched the invocation
│   └── MissingArgument    - Required argument absent
└── CaptchaChallenge       - Discord requires a captcha

HTTPError

HTTPError is raised whenever Discord’s REST API responds with a 4xx or 5xx status code. The exception exposes the raw HTTP status, Discord’s internal error code, and the human-readable message from the response body.

import alterself

bot = alterself.Client(token="TOKEN", prefix=".")

@bot.command()
async def safe_send(ctx, *, text: str):
    try:
        await bot.http.send_message(ctx.channel_id, content=text)
    except alterself.HTTPError as e:
        print(f"HTTP {e.status} - Discord code {e.code}: {e.text}")
        await ctx.reply(f"❌ Failed to send: `{e.text}`")

bot.run()

Common Discord Error Codes

Code	Meaning
`10003`	Unknown channel
`10004`	Unknown guild
`10008`	Unknown message
`50001`	Missing access
`50013`	Missing permissions
`50035`	Invalid form body

Check e.code (the Discord JSON error code) rather than e.status (the HTTP status) for precise branching. Many different error conditions all return 400 Bad Request but carry distinct code values.

SessionClosed

SessionClosed is raised when Discord closes the WebSocket connection with a non-resumable close code. alterself will not attempt to reconnect automatically when this exception is raised, because most fatal close codes indicate a configuration problem rather than a transient network hiccup.

try:
    bot.run()
except alterself.SessionClosed as e:
    print(f"Gateway closed - code {e.code}")

Fatal Gateway Close Codes

Code	Meaning
`4004`	Token invalid
`4010`	Invalid shard
`4011`	Sharding required
`4012`	Invalid API version
`4013`	Invalid intents
`4014`	Disallowed intents

Close code 4004 means your token is invalid or has been invalidated (e.g. password changed, token reset). This is unrecoverable, so no amount of reconnection will help. Check your token immediately and update it before restarting the bot.

CaptchaChallenge

When Discord decides it needs human verification for an action (usually account-sensitive HTTP requests), it responds with a captcha challenge rather than the expected data. alterself surfaces this as a CaptchaChallenge exception instead of silently failing.

try:
    await bot.http.join_guild("some-invite")
except alterself.CaptchaChallenge as e:
    print(f"Captcha required - sitekey: {e.sitekey}")
    print(f"rqdata: {e.rqdata}")
    # Pass e.sitekey and e.rqdata to your captcha-solving service

The two key attributes are:

Attribute	Description
`e.sitekey`	The hCaptcha site key needed to generate a solution token
`e.rqdata`	The `rqdata` value required by Discord’s captcha implementation

Pass both to your chosen captcha-solving service, retrieve the solution token, then retry the request with captcha_key=<token> in the request body.

CommandError and its Subclasses

CommandError and its subclasses are raised inside the command dispatch pipeline. You handle them by registering an on_command_error event listener.

@bot.on_event
async def on_command_error(ctx, error):
    if isinstance(error, alterself.ConversionFailed):
        await ctx.reply(f"❌ Bad argument: `{error.argument}` couldn't be converted.")
    elif isinstance(error, alterself.MissingArgument):
        await ctx.reply(f"❌ Missing required argument: `{error.param}`.")
    elif isinstance(error, alterself.CommandNotFound):
        pass   # silently ignore unknown commands
    else:
        raise error   # re-raise anything unexpected

CheckFailed

CheckFailed is raised when a @bot.check or @command.check decorator returns a falsy value. By default, alterself silently drops the invocation, so the command simply does not run and no error message is sent. If you want to notify the user, handle it explicitly in on_command_error:

@bot.on_event
async def on_command_error(ctx, error):
    if isinstance(error, alterself.CheckFailed):
        await ctx.reply("🚫 You don't have permission to use that command.")

CheckFailed is intentionally silent by default. This keeps your selfbot from drawing attention when commands are triggered by other users who don’t meet your access requirements.

Global Error Handler

For a production selfbot, register a single on_command_error handler that covers every CommandError subclass and logs everything else:

import traceback

@bot.on_event
async def on_command_error(ctx, error):
    if isinstance(error, alterself.CheckFailed):
        return   # silently skip

    if isinstance(error, alterself.MissingArgument):
        await ctx.reply(f"❌ Missing argument: `{error.param}`.")
        return

    if isinstance(error, alterself.ConversionFailed):
        await ctx.reply(f"❌ Invalid value for `{error.param}`.")
        return

    if isinstance(error, alterself.CommandNotFound):
        return   # ignore unknown prefixed messages

    # Anything else is unexpected. Log the full traceback.
    traceback.print_exception(type(error), error, error.__traceback__)

Get Started

Core Concepts

Guides

Handling Errors and Exceptions in alterself Selfbots

Exception Hierarchy

HTTPError

Common Discord Error Codes

SessionClosed

Fatal Gateway Close Codes

CaptchaChallenge

CommandError and its Subclasses

CheckFailed

Global Error Handler

​Exception Hierarchy

​HTTPError

​Common Discord Error Codes

​SessionClosed

​Fatal Gateway Close Codes

​CaptchaChallenge

​CommandError and its Subclasses

​CheckFailed

​Global Error Handler

Exception Hierarchy

HTTPError

Common Discord Error Codes

SessionClosed

Fatal Gateway Close Codes

CaptchaChallenge

CommandError and its Subclasses

CheckFailed

Global Error Handler