A work poller repeatedly calls the API's poll endpoint with a capped block timeout, yields each received BetaSelfHostedWork item after acknowledging it, and manages backoff and error recovery for both poll and ack failures. When auto_stop=True, the poller ensures cleanup via work.stop even on consumer exceptions, and silently tolerates 409 responses (already-stopped work) while logging other errors and continuing the poll loop. In the poller, backpressure refers to slowing the request rate — via jitter sleep on empty polls and capped exponential backoff on errors — to avoid overwhelming the API endpoint.
src/anthropic/lib/environments/_poller.py exports three public symbols: iter_work, aiter_work, and POLL_BLOCK_MS.[1] aiter_work is the async counterpart to iter_work with identical semantics; it uses anyio.sleep instead of time.sleep for async-safe waiting.[1]
POLL_BLOCK_MS is set to 999 ms because the API caps block_ms at 999; client-side jitter is used between empty polls instead of relying on a higher server-side value.[1] On an empty poll, iter_work sleeps for a random jitter between 1 and 3 seconds before re-polling, to avoid a tight busy-loop.[1] The backoff cap for failed polls is 60 seconds (_POLL_BACKOFF_CAP = 60.0).[1]
Each BetaSelfHostedWork item yielded by iter_work / aiter_work has already been ack'd by the poller before it is yielded to the caller.[1] When auto_stop=True, iter_work wraps each yield in a try/finally so work.stop is called even if the consumer's loop body raises an exception; a 409 on stop is silently ignored.[1] The extra_headers parameter is threaded into every poll, ack, and stop call per-request without mutating the bound client; a header given here overrides the bound client's same-named default for that one request only.[1]
If a poll fails with a fatal 4xx error, iter_work / aiter_work re-raises immediately and stops the loop — unlike ack failures, fatal poll errors are not swallowed.[1] If an ack fails with a fatal 4xx error, the poller calls work.stop(force=True) on the item via _force_stop_quietly and then continues polling — it does not raise or stop the loop.[1] _force_stop_quietly calls work.stop(force=True) on an item that cannot be processed; a 409 response is silently ignored (meaning the work already stopped), but any other error is logged at ERROR level and not re-raised, so the poll loop can continue.[1]
Sources