# HTTPX and outbound HTTP calls

HTTPX is the library Connect uses to make outbound HTTP requests. It reaches carriers, the WhatsApp Cloud API, payment gateways, model providers and the services a business connects. Every call has a timeout. A transport failure is reported for what it means: not delivered, or outcome unknown. It is never treated as success.

- **Status:** Reference
- **Audience:** both, developer
- **Last verified:** 2026-11-02
- **Canonical:** https://connectbyjbrh.com/docs/technology/httpx/

## What it is

HTTPX is a Python HTTP client from the Encode project. It offers both a synchronous and an asynchronous API with the same shape, connection pooling, timeouts by default and optional HTTP/2.

Connect also lists `requests` in its requirements, which `google-auth` uses for token refreshes. Connect's own provider calls use HTTPX.

**Category** — HTTP client
**Version in Connect** — `httpx>=0.27`
**Used in** — About 35 modules, among them `comms_providers.py`, `llm.py`, `gmail_writeback.py`, `tenant_send.py`, `employee_integrations.py`
**Official site** — [python-httpx.org](https://www.python-httpx.org/)

## Where Connect uses it

| Place in Connect | What it does there |
|---|---|
| `comms_providers.py` | Carrier and messaging requests: SMS, WhatsApp and outbound calls |
| `llm.py` and the assistant adapters | Model provider APIs |
| `employee_integrations.py` | A business's own REST APIs, MCP servers and webhooks, after an address check that refuses private networks |
| Mail modules | Gmail write-back and connected mailbox APIs |

## How it connects

1. A Connect module builds the request with its credentials from settings
2. HTTPX sends it with an explicit timeout
3. A connection error becomes `carrier_unreachable`, and a timeout `outcome_uncertain`
4. A non-success answer is classified (rate limited, refused, invalid)
5. The caller records the provider's own acknowledgement as evidence

## Benefits and limits

What it gives Connect:

- One client for sync and async code.
- Default timeouts. A hung provider cannot hold a request open forever.
- Easy to fake in tests, so suites run without reaching a real provider.

Where it stops, and what Connect does about it:

- A timeout after sending does not mean the request failed. It may have arrived. Connect calls that *uncertain* and does not retry a send blindly ([idempotency](/docs/technology/idempotency/)).
- HTTPX does not retry by itself. Retries are Connect's decision, per operation ([retries](/docs/technology/retry/)).
- HTTP/2 needs an extra package and is not enabled.

## Security and privacy

- TLS certificates are verified. No call turns verification off.
- Integration calls to a business's own endpoints are refused for private and loopback addresses, which closes the server-side request forgery path.
- Credentials go in headers, never in URLs that end up in logs.

## Licence, cost and versions

| Question | Answer |
|---|---|
| Licence | BSD-3-Clause |
| Cost | None |
| Version | `httpx>=0.27` (a floor) |
| Compatibility | Python 3.12 |

## Troubleshooting

**`outcome_uncertain` on a send** — The provider did not answer in time after the request was sent. Check the provider's console before sending again.
**`carrier_rate_limited`** — The provider returned 429. Wait, and the queue paces itself.
**SSL verification error** — The provider's certificate chain or the host's CA bundle is wrong. Never disable verification.

## Official references

- [HTTPX documentation](https://www.python-httpx.org/)
- [HTTPX timeouts](https://www.python-httpx.org/advanced/timeouts/)
- [RFC 9110: HTTP semantics](https://www.rfc-editor.org/rfc/rfc9110)

## Questions

### Why does Connect say a message's outcome is uncertain?

Because a timeout after sending cannot tell delivered from lost. Treating it as failed would invite a duplicate, and treating it as sent would be a guess. Uncertain is the honest state until the provider confirms.

### Can a connected integration call an internal address?

No. Private, loopback and link-local destinations are refused before any request is made.

## Related

- [HTTP](https://connectbyjbrh.com/docs/technology/http/)
- [Retries and backoff](https://connectbyjbrh.com/docs/technology/retry/)
- [Idempotency](https://connectbyjbrh.com/docs/technology/idempotency/)
- [Rate limiting](https://connectbyjbrh.com/docs/technology/rate-limit/)

## What this page is based on

- `backend/app/comms_providers.py`
- `backend/app/employee_integrations.py`
- `requirements.txt`
- https://www.python-httpx.org/
