Connect by JBRH Open Connect

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 What this means
Audience
both, developer
Last verified
Product version
6.3.2

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

Where Connect uses it#

Place in ConnectWhat it does there
comms_providers.pyCarrier and messaging requests: SMS, WhatsApp and outbound calls
llm.py and the assistant adaptersModel provider APIs
employee_integrations.pyA business's own REST APIs, MCP servers and webhooks, after an address check that refuses private networks
Mail modulesGmail 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).
  • HTTPX does not retry by itself. Retries are Connect's decision, per operation (retries).
  • 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#

QuestionAnswer
LicenceBSD-3-Clause
CostNone
Versionhttpx>=0.27 (a floor)
CompatibilityPython 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#

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.