Timeouts and cancellation

Each HTTP attempt times out after 90 seconds by default, since some enrichments take more than 60 seconds. Every API method accepts the keyword arguments timeout (seconds per attempt, or an httpx.Timeout), max_retries and headers.

With AsyncReverseContact, use asyncio.timeout() or cancel the call's asyncio task. The synchronous client has no cancel handle. Limit each call with timeout, and each job wait with job.wait(timeout=...). Cancellation stops your code from waiting but does not cancel a job on the server.

import asyncio
import os

from reversecontact import AsyncReverseContact


async def main() -> None:
    async with AsyncReverseContact(api_key=os.environ["RC_API_KEY"]) as client:
        async with asyncio.timeout(30):
            usage = await client.usage.retrieve(timeout=10.0, max_retries=1)
        if usage.quotas and usage.quotas.workspace and usage.quotas.workspace.credits:
            print("Credits left:", usage.quotas.workspace.credits.left)


asyncio.run(main())

HTTP attempts and polling deadlines

On an API request, timeout limits each HTTP attempt through httpx's timeout settings. Retries can extend the total elapsed time. For polling requests, finite HTTP timeout components increase to at least wait + 15 seconds. A wait() helper then caps those components at the time remaining before its overall deadline.

On job.wait(), client.jobs.wait(), client.bulk.wait() and client.lists.operations.wait(), timeout is an overall deadline. The default is 1800 seconds. The helpers accept poll_wait from 0 to 20 and raise ReverseContactError for invalid polling values or a non-finite, negative timeout. A synchronous wait can overrun by one bounded HTTP phase. An async wait uses an asyncio deadline.

The wait helpers handle polling failures separately from per-request max_retries. They retry eligible consecutive API or connection failures up to four times, within the deadline. A successful poll resets the retry count.

Stop server-side bulk work

Local asyncio cancellation does not cancel server-side work. For Bulk jobs, call client.bulk.cancel(). For a List operation, call client.lists.operations.cancel(). These are explicit API operations with their own return values.

See Async jobs to resume a timed-out enrichment and Errors and retries for transport error handling.

Return to the Python SDK overview.