1class DeferJob(Exception):
 2    """Signal that a job should be deferred and re-tried later.
 3
 4    Unlike regular exceptions that indicate errors, DeferJob is used for expected
 5    delays like:
 6    - Waiting for external resources (API rate limits, data not ready)
 7    - Polling for status changes
 8    - Temporary unavailability
 9
10    Example:
11        # Finite retries - will fail if data never becomes ready
12        if not data.is_ready():
13            raise DeferJob(delay=60, increment_retries=True)
14
15        # Infinite retries - safe for rate limits
16        if rate_limited():
17            raise DeferJob(delay=300, increment_retries=False)
18    """
19
20    def __init__(self, *, delay: int, increment_retries: bool = False):
21        self.delay = delay
22        self.increment_retries = increment_retries
23        super().__init__(f"Job deferred for {delay} seconds")