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

Aberta Para iniciantes
#986 1 comentário 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

@henricop já está trabalhando nisso.

Desde 7/11/2026.

  • #989 de @henricop — aberto

Avaliação

Dificuldade
1/5
Tempo estimado
1-3 horas
Facilidade para iniciantes
90/100
Tipo de issue
Documentação
Clareza
Claramente especificada
Status de atividade
Ativa
Stack de tecnologia
python
Domínio
documentation

Direção de pesquisa

Comece pela seção “Handling Exceptions” em README.md e confirme o comportamento em twilio/base/exceptions.py, twilio/http/http_client.py e twilio/http/async_http_client.py. Atualize o README para diferenciar respostas de erro da API de exceções de transporte e mostrar como capturá-las; a tarefa estará concluída quando os exemplos corresponderem ao comportamento síncrono e assíncrono documentado.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.

Linguagem predominante
Python
Estrelas
2.1k
Forks
821
Merge médio
9h 33min
PRs com merge (30d)
3

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de twilio/twilio-python

Todas as issues de twilio/twilio-python

Issues semelhantes

Mais issues de Python

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.