feat(errors): expose Retry-After header on UsageLimitExceededError

[stihahi]

Summary

The Tavily REST API returns a Retry-After header on 429 Too Many Requests responses (docs),
but the Python SDK currently discards it and raises
UsageLimitExceededError(detail) with no way for callers to recover the
server's recommended wait. Applications implementing client-side
throttling (e.g. production workloads hitting the 1000 RPM tier) have to
fall back to a fixed exponential backoff and guess at the real cool-down.

This PR exposes the header value on the exception so callers can honor
the server's recommendation.

Changes

tavily/errors.py

• Add UsageLimitExceededError.retry_after: Optional[float], defaulting
  to None for backward compatibility.

• Add internal _parse_retry_after(headers) helper. Semantics follow
  urllib3.util.Retry.parse_retry_after — parse
  RFC 7231 §7.1.3:

  • non-negative decimal integer of seconds, e.g. "120" (clamped to ≥ 0)
  • HTTP-date, e.g. "Wed, 21 Oct 2015 07:28:00 GMT" (converted to
    seconds from now, past dates clamp to 0)

  Returns None when the header is absent, empty, fractional, NaN/inf,
  or otherwise unparseable.

• Case-insensitive header name lookup is done explicitly, so callers
  passing a plain dict (not only requests/httpx header containers)
  work correctly.

tavily/tavily.py, tavily/async_tavily.py

• At every 429 raise site (14 total: sync + async × search, extract,
  crawl, map, research request, research streaming), pass
  retry_after=parse_retry_after(response.headers).

tests/test_retry_after.py (new)

Covers:

• sync + async: integer-seconds Retry-After is exposed on the exception
• sync: HTTP-date Retry-After is parsed and exposed
• sync: malformed Retry-After yields retry_after=None
• sync + async: missing header yields retry_after=None
• constructor: retry_after defaults to None and accepts explicit value
• helper edge cases: fractional rejected, negative clamps to 0, NaN/inf
  rejected, case-insensitive header name, past HTTP-date clamps to 0,
  empty/whitespace-only value returns None

All existing tests still pass (88 passed including the 14 new cases).

Backward compatibility

Non-breaking.

• UsageLimitExceededError(message) still works — retry_after is a
  default-None kwarg.
• Callers doing except UsageLimitExceededError as e: str(e) are
  unaffected.
• Opt-in for new consumers:
  except UsageLimitExceededError as e: sleep(e.retry_after or fallback).

Example

from tavily import TavilyClient
from tavily.errors import UsageLimitExceededError
import time

client = TavilyClient()
while True:
    try:
        results = client.search("quarterly reports")
        break
    except UsageLimitExceededError as e:
        wait = e.retry_after if e.retry_after is not None else 5.0
        time.sleep(wait)

Notes for reviewers

• Kept the diff surgical. Each 429 site now reads
  retry_after=parse_retry_after(response.headers) — a follow-up could
  extract the full error-response-to-exception mapping into a shared
  helper, but that refactor is independent of this fix and intentionally
  deferred.
• parse_retry_after accepts any mapping (works for both requests
CaseInsensitiveDict and httpx Headers).
• HTTP-date branch uses email.utils.parsedate_to_datetime (stdlib).
  Naive datetimes are assumed UTC.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 46de255. Configure here.}