diff --git a/README.md b/README.md index 6c25c0a81..e94f24bb0 100644 --- a/README.md +++ b/README.md @@ -266,11 +266,14 @@ client.http_client.logger.setLevel(logging.INFO) ### Handling Exceptions -Version 8.x of `twilio-python` exports an exception class to help you handle exceptions that are specific to Twilio methods. To use it, import `TwilioRestException` and catch exceptions as follows: +`TwilioRestException` represents error responses from the Twilio API. Transport +failures, such as a connection failure or timeout, propagate from the default +HTTP client as `requests` exceptions instead. Catch them separately: ```python from twilio.rest import Client from twilio.base.exceptions import TwilioRestException +from requests.exceptions import RequestException, Timeout account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" auth_token = "your_auth_token" @@ -281,8 +284,42 @@ try: body="Hello there!") except TwilioRestException as e: print(e) +except Timeout as e: + print("The request timed out; its outcome may be unknown:", e) +except RequestException as e: + print("The HTTP request failed:", e) ``` +`requests.exceptions.ConnectionError` and `requests.exceptions.Timeout` are both +subclasses of `requests.exceptions.RequestException`; neither is a +`TwilioRestException`. A timeout does not confirm whether the API processed the +request, so retry only when the operation can safely be repeated. + +When using `AsyncTwilioHttpClient` as shown in +[Asynchronous API Requests](#asynchronous-api-requests), catch `aiohttp.ClientError` +for client/connection failures and `asyncio.TimeoutError` for timeouts separately +from `TwilioRestException`: + +```python +import asyncio +from aiohttp import ClientError +from twilio.base.exceptions import TwilioRestException + +async def send_message(client): + try: + return await client.messages.create_async(to="+12316851234", from_="+15555555555", + body="Hello there!") + except TwilioRestException as e: + print(e) + except asyncio.TimeoutError as e: + print("The request timed out; its outcome may be unknown:", e) + except ClientError as e: + print("The asynchronous HTTP request failed:", e) +``` + +These exception types describe the default HTTP clients; a custom HTTP client +may expose different transport exceptions. + ### Generating TwiML To control phone calls, your application needs to output [TwiML][twiml].