[henricop]

Fixes #986

Clarify that TwilioRestException represents an API error response, while the default HTTP clients propagate transport errors from requests or aiohttp/asyncio. Add separate sync/async handling examples and explain that a timeout can leave the operation's outcome unknown. No SDK behavior, wrapping or retries change.

Validation: make test passes all 651 tests, including analysis/format checks. Both displayed README snippets compile and were executed with mocked transports; checks cover sync connection errors/timeouts, async client errors/timeouts and API errors without credentials or network requests.

Prepared with Codex assistance and verified locally. Thanks to @hidingmyname for the detailed report.

Checklist

• I acknowledge that all my contributions will be made under the project's license
• I have made a material change to the repo (functionality, testing, spelling, grammar)
• I have read the Contribution Guidelines and my PR follows them
• I have titled the PR appropriately
• I have updated my branch with the main branch
• I have added tests that prove my fix is effective or that my feature works — not applicable to this documentation-only change; examples were validated offline and the existing full suite passes.
• I have added the necessary documentation about the functionality in the appropriate .md file
• I have added inline documentation to the code I modified — not applicable; no Python source changes.