Docs: "Handling Exceptions" should mention that network errors are not `TwilioRestException`

Ouverte Adaptée aux débutants
#986 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

@henricop y travaille déjà.

Depuis le 7/11/2026.

  • #989 par @henricop — ouverte

Évaluation

Difficulté
1/5
Temps estimé
1-3 heures
Accessibilité débutants
90/100
Type d'issue
Documentation
Clarté
Clairement spécifiée
Activité
Active
Stack technique
python
Domaine
documentation

Piste de recherche

Commencez par la section « Handling Exceptions » de README.md et confirmez le comportement dans twilio/base/exceptions.py, twilio/http/http_client.py et twilio/http/async_http_client.py. Mettez à jour le README pour distinguer les réponses d’erreur de l’API des exceptions de transport et montrer comment les intercepter ; le travail sera terminé lorsque les exemples correspondront au comportement synchrone et asynchrone documenté.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

Location (twilio/twilio-python @ default branch 74b9629):

try:
  message = client.messages.create(to="+12316851234", from_="+15555555555",
                                   body="Hello there!")
except TwilioRestException as e:
  print(e)
# twilio/http/http_client.py
        response = session.send(
            prepped_request,
            allow_redirects=allow_redirects,
            timeout=timeout,
            **settings,
        )

Problem

The README's "Handling Exceptions" section shows only except TwilioRestException. TwilioRestException is documented as "A generic 400 or 500 level exception from the Twilio API", i.e. it covers responses returned by the API. When the request never gets a response (DNS failure, connection refused, timeout) the default TwilioHttpClient lets the requests exception propagate as-is, so requests.exceptions.ConnectionError / requests.exceptions.Timeout escape that handler. The README doesn't mention this, so code written from the example can miss transport failures entirely.

I think propagating the original requests exception is a reasonable design: it keeps the exact cause and lets callers distinguish timeouts (possibly retryable) from other errors. This request is only about documenting it.

Reproduction

With session.send raising, TwilioHttpClient.request() raises the original exception (observed with mocked Session.send):

requests.exceptions.ConnectionError: Connection refused
requests.exceptions.Timeout: execution expired

Environment:

  • Commit: 74b96296b0805986252b798bda4bca90341487ee (main, twilio 9.12.0)
  • Toolchain: Python 3.13.18

Already fixed in twilio/twilio-ruby

PR: https://github.com/twilio/twilio-ruby/pull/470 — "breaking: Catch and wrap Faraday client errors" (merged 2019-09-16T16:35:47Z, merge commit a5d428281af). The same gap was addressed in the Ruby library, but by a different route: it wraps Faraday client errors in Twilio::REST::TwilioError and adds a "Handling Errors" README section, as a breaking change. The wrapping is shown for context and is not proposed here; only making the behaviour explicit to users is.

How twilio-ruby fixed it:

--- a/lib/twilio-ruby/http/http_client.rb
+++ b/lib/twilio-ruby/http/http_client.rb
@@ -52,6 +50,14 @@ def _request(request)
...
+      def send(request)
+        @connection.send(request.method.downcase.to_sym,
+                         request.url,
+                         request.method == 'GET' ? request.params : request.data)
+      rescue Faraday::ClientError => e
+        raise Twilio::REST::TwilioError, e
+      end
--- a/README.md
+++ b/README.md
@@ -98,30 +98,38 @@ auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
...
+### Handling Errors
...
+```ruby
+begin
+  messages = @client.messages.list(limit: 20)
+rescue Twilio::REST::TwilioError => e
+  puts e.message
+end
+```

Suggested fix

Docs only: after the "Handling Exceptions" example, the README states that TwilioRestException covers API error responses, that transport failures surface as requests (sync) or aiohttp (async) exceptions, and shows how to catch them; wrapping transport errors or adding retries is not proposed:

diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -283,6 +283,23 @@ except TwilioRestException as e:
   print(e)
 ```
 
+`TwilioRestException` represents an error response returned by the Twilio API. If the request gets no response at all (for example a DNS failure, a refused connection or a timeout), the default `TwilioHttpClient` lets the underlying `requests` exception propagate, so `requests.exceptions.ConnectionError`, `requests.exceptions.Timeout` and the other `requests.exceptions.RequestException` subclasses are not caught by `except TwilioRestException`. The async client (`AsyncTwilioHttpClient`) raises aiohttp's exceptions in the same situation. To handle these failures, catch them separately:
+
+```python
+from requests.exceptions import ConnectionError, Timeout
+from twilio.base.exceptions import TwilioRestException
+
+try:
+  message = client.messages.create(to="+12316851234", from_="+15555555555",
+                                   body="Hello there!")
+except TwilioRestException as e:
+  print(e.status, e.code)  # the API returned an error
+except Timeout:
+  pass  # no response in time; the outcome is unknown, decide whether to retry
+except ConnectionError:
+  pass  # the API could not be reached
+```
+
 ### Generating TwiML
 
 To control phone calls, your application needs to output [TwiML][twiml].

Documentation-only change, so there is no failing test; the documented behaviour was checked on 74b9629 (Python 3.13.18) with Session.send mocked to raise ConnectionError and Timeout: TwilioHttpClient.request() re-raises both unchanged, and neither is a TwilioRestException.

I can submit a PR for this.

Checked: #327 (hanging behind proxy), #485 (timeout parameter) and #630 (timeout type hint) don't cover how transport errors are surfaced or documented.

Langage dominant
Python
Étoiles
2.1k
Forks
821
Merge moyen
9 h 33 min
PR mergées (30 j)
3

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de twilio/twilio-python

Toutes les issues de twilio/twilio-python

Issues similaires

Plus d'issues Python

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.