Configure httpx clients for the hCaptcha API

Use sync or native async httpx transports with the easycaptcha SDK and manage owned sessions, timeouts, and response states deliberately.

Choose the synchronous or asynchronous class

The easycaptcha httpx backend provides HttpxClient and AsyncHttpxClient. Both use the same request types and public operations. Choose the sync class for a synchronous worker and the async class when the rest of the application already runs an event loop. Install easycaptcha-sdk[httpx] for either.

Avoid making transport selection part of every job’s business logic. Construct the appropriate client at an application boundary and pass the public interface to code that manages the lifecycle.

Supply a session when the application owns networking

import os
import httpx
from easycaptcha.backends.httpx import HttpxClient

with httpx.Client() as session:
    with HttpxClient(
        os.environ["EASYCAPTCHA_API_KEY"],
        session=session,
        timeout=45,
    ) as client:
        balance = client.get_balance()
        print(balance["balance_microcents"])

The outer context owns the supplied session. Without session=, the SDK creates and closes its own session. Make ownership explicit so shutdown neither leaks connections nor closes a session another component still needs.

The SDK request timeout is a transport setting. A job’s lifetime is separate: ending the HTTP wait does not cancel server-side work. If creation returns a pending task, retain its ID and retrieve it again. If creation times out without an ID, classify the outcome as uncertain instead of automatically sending another creation request.

Keep response handling at the SDK boundary

A non-success HTTP response and a job with status: "failed" are separate cases. Do not hide the latter by treating a successful JSON decode as task completion. Read the status before accessing a typed result.

If your application customizes the session, test its hooks, connection limits, and retry behavior with the actual SDK operations. Keep Authorization headers out of traces. Test a long-held request and make sure your upstream application timeout allows the chosen hold interval plus network overhead.

The async guide supplies an event-loop-friendly polling example. The long-polling guide explains the difference between the server’s wait interval and the client’s overall deadline.