⚠️ Errors#

Exceptions in pywa are a key mechanism for letting you know what went wrong and why. They appear in two main ways:

Raised exceptions — when something fails immediately (e.g., invalid parameters).
Returned errors — when the API reports an error asynchronously via a message status update.

Basic Example#

Most exceptions are raised directly when you attempt an invalid action:

import logging
from pywa import WhatsApp, types, errors

wa = WhatsApp(...)

try:
    wa.send_message(..., buttons=[
        types.Button(title="click 1", callback_data="click"),
        types.Button(title="click 2", callback_data="click"),  # ⚠️duplicate callback_data
    ])
except errors.InvalidParameter as e:
    logging.error(f"Duplicated `callback_data` in buttons: {e}")

Message Status Errors#

Some errors are not raised immediately but instead appear as part of a MessageStatus update.

For example:

Sending a non-template message outside the 24h conversation window → ReEngagementMessage
Sending invalid media (wrong file type, too large, invalid URL, etc.) → MediaUploadError

These errors surface in the status update rather than raising an exception directly.

That’s why it’s important to always register a handler for failed message statuses:

import logging
from pywa import WhatsApp, types, filters

wa = WhatsApp(...)

@wa.on_message_status(filters.failed)
def handle_failed_message(client: WhatsApp, status: types.MessageStatus):
    logging.error("Message failed to send to %s: %s",
        status.sender, status.error
    )

Handling Specific Errors#

You can also filter and handle specific error types:

import logging
from pywa import WhatsApp, filters, errors

wa = WhatsApp(...)

wa.send_message(to="972501234567", text="Hello")  # 24h window closed
wa.send_image(  # nonexistent image
    to="972501234567",
    image="https://example.com/this-image-does-not-exist.jpg",
    caption="Not found"
)
wa.send_document(  # file too large
    to="972501234567",
    document="https://example.com/document-size-is-too-big.pdf",
    filename="big.pdf"
)

@wa.on_message_status(filters.failed_with(errors.ReEngagementMessage))
def handle_failed_reengagement(client: WhatsApp, status: types.MessageStatus):
    logging.error("Message failed to send to %s: %s",
        status.from_user.wa_id, status.error
    )

@wa.on_status_message(filters.failed_with(errors.MediaUploadError))
def handle_failed_sent_media(client: WhatsApp, status: types.MessageStatus):
    logging.error("Message failed to send to %s: %s",
        status.from_user.wa_id, status.error
    )
    status.reply_text("Sorry, I can't upload this file")

@wa.on_status_message(filters.failed_with(errors.MediaDownloadError))
def handle_failed_received_media(client: WhatsApp, status: types.MessageStatus):
    logging.error("Got a media download error from %s: %s",
        status.from_user.wa_id, status.error
    )
    status.reply_text("Sorry, I can't download this file")

Incoming Errors (Unsupported Messages)#

If a user sends an unsupported message type (e.g., poll), you’ll receive a Message with type UNSUPPORTED and an error of UnsupportedMessageType.

from pywa import WhatsApp, types, filters

wa = WhatsApp(...)

@wa.on_message(filters.unsupported)
def handle_unsupported_message(client: WhatsApp, msg: types.Message):
    msg.reply_text("Sorry, I don't support this message type yet")

Catching All Exceptions#

Since all exceptions inherit from WhatsAppError, you can catch everything with one block:

from pywa import WhatsApp, errors

wa = WhatsApp(...)

try:
    wa.send_message(...)
except errors.WhatsAppError as e:
    print(f"Error: {e}")

Base Exception#

class pywa.errors.WhatsAppError#

Bases: Exception

Base dataclass for WhatsApp errors.

Variables:

code (int) – The error code.
message (str) – The error message.
details (str | None) – The error details (optional).
fbtrace_id (str | None) – The Facebook trace ID (optional).
href (str | None) – The href to the documentation (optional).
raw_response (httpx.Response | None) – The httpx.Response obj that returned the error (optional, only if the error was raised from an API call).
subcode (int | None) – The error subcode (optional).
type (str | None) – The error type (optional).
is_transient (bool | None) – Whether the error is transient (optional).
user_title (str | None) – The user-facing title for the error (optional).
user_msg (str | None) – The user-facing message for the error (optional).

Categories of Exceptions#

All exceptions fall into one of these categories:

⚠️ Errors

Contents