⚠️ Errors

⚠️ Errors#

Exceptions are important part of the pywa library. They are used to tell you what went wrong and why.

Most of the exceptions are raised when you try to do something like sending a message:

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"),
    ])
except errors.InvalidParameter as e:  # duplicate callback_data in buttons (`click`)
    logging.error(f"Duplicated callback_data in buttons: {e}")

But there are also errors that are not raised, but can be returned in a message status.

For example, you can sometimes try to send_message() to a user that the last time you sent a message to him was less than 24 hours ago, if this message is not a Template message, you will not get an exception, but you will get MessageStatus on FAILED status with .error attribute with value of ReEngagementMessage.

The same goes for media messages: if you try to send a invalid media (unsupported file type, too big file, invalid url, etc.), You will not get the exception, when you try to send the message, but in the message status error attribute (MediaUploadError).

That’s why it’s important to always register a handler for failed status messages, so you can know when a message failed to send:

import logging
from pywa import WhatsApp, types, filters

wa = WhatsApp(...)

@wa.on_message_status(filters.failed)  # filter for failed message statuses
def handle_failed_message(client: WhatsApp, status: types.MessageStatus):
    logging.error("Message failed to sent to %s: %s. details: %s",
        status.from_user.wa_id, status.error.message, status.error.details
    )

You can also handle specific errors, for example, if you want to handle only media errors:

import logging
from pywa import WhatsApp, filters, errors

wa = WhatsApp(...)

wa.send_message(to="972501234567", text="Hello")  # this conversation window is closed (24 hours passed)

wa.send_image(  # this image does not exist
    to="972501234567",
    image="https://example.com/this-image-does-not-exist.jpg",
    caption="Not found"
)

wa.send_document(  # this document is too big
    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 sent to %s: %s. details: %s",
        status.from_user.wa_id, status.error.message, status.error.details
    )

@wa.on_status_message(filters.failed_with(errors.MediaUploadError))
def handle_failed_sent_media(client: WhatsApp, status: types.MessageStatus):
    logging.error("Message failed to sent to %s: %s. details: %s",
        status.from_user.wa_id, status.error.message, status.error.details
    )
    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. details: %s",
        status.from_user.wa_id, status.error.message, status.error.details
    )
    status.reply_text("Sorry, I can't download this file")

Another example for “incoming” errors is for unsupported messages: if the user sends unsupported message type (like pool), you will get the message with type of UNSUPPORTED and with 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")

All the exceptions are inherited from WhatsAppError, so you can catch all of them with one exception:

1from pywa import WhatsApp, errors
2
3wa = WhatsApp(...)
4
5try:
6    wa.send_message(...)
7except errors.WhatsAppError as e:
8    print(f"Error: {e}")

Base Exception#

class pywa.errors.WhatsAppError#

Bases: Exception

Base exception for all WhatsApp errors.

Variables:

  • error_code – The error code.

  • error_subcode – The error subcode (optional).

  • type – The error type (optional).

  • message – The error message.

  • details – The error details (optional).

  • fbtrace_id – The Facebook trace ID (optional).

  • href – The href to the documentation (optional).

  • raw_response – The httpx.Response obj that returned the error (optional, only if the error was raised from an API call).

The exceptions are divided into 5 categories: