refactor(errors)!: unify request failures under a DataRetrievalError taxonomy

[thodson-usgs]

Problem

An HTTP failure surfaced as a different exception type depending on which module made the request, so there was no single except for "any dataretrieval request failure":

Path	Raised on failure (before)
legacy query() (wqp, nwis, ngwmn, nldi)	ValueError, or NoSitesError(Exception)
waterdata	RateLimited / ServiceUnavailable (RuntimeError), RequestTooLarge (ValueError), ChunkInterrupted (RuntimeError)
nadp, streamstats	bare httpx.HTTPStatusError

The same HTTP condition also produced near-homonym twins — ServiceUnavailableError vs ServiceUnavailable, RequestTooLargeError vs RequestTooLarge — distinguished only by an -Error suffix that silently encoded which code path raised it.

Change

Add dataretrieval.exceptions (dependency-free; every type re-exported at top level as dataretrieval.<Name>), rooted at DataRetrievalError, with two intermediate bases that name the axes a caller actually reasons about:

DataRetrievalError(Exception)
├─ BadRequestError(…, ValueError)        # 400
├─ NotFoundError(…, ValueError)          # 404
├─ RequestTooLarge(…, ValueError)        # base: the request is too large to satisfy
│   ├─ URLTooLong                        #   one request the server rejected (HTTP 414 / client-side)
│   └─ Unchunkable                       #   the chunker can't split the call small enough
├─ NoSitesError                          # empty result
└─ TransientError(…, RuntimeError)       # base: temporary failure worth a retry (carries retry_after)
    ├─ RateLimited                       #   429
    └─ ServiceUnavailable                #   5xx

• One type per condition, shared by both paths — a 5xx raises ServiceUnavailable and a too-long URL raises a RequestTooLarge subclass whether the request came from the legacy query() path or the Water Data chunker.
• Catch a whole family — except RequestTooLarge covers 414 + unchunkable; except TransientError covers any retryable failure; the chunker's retry check collapses to a single isinstance(exc, TransientError).
• Built-in compatibility by kind — fatal client errors are also ValueError, transient transport errors also RuntimeError, so existing except ValueError / except RuntimeError keep working.
• query()'s inline status ladder is extracted into a reusable _raise_for_status(); NoSitesError now subclasses DataRetrievalError (was Exception).

try:
    df, md = dataretrieval.wqp.get_results(...)
except dataretrieval.TransientError as e:
    time.sleep(e.retry_after or 1); ...   # handle just the retryable ones
except dataretrieval.DataRetrievalError:
    ...                                   # any failure, any module

Breaking changes

• The legacy query() path raises typed errors instead of ad-hoc ValueErrors (400 → BadRequestError, 404 → NotFoundError, 414 / over-long URL → URLTooLong).
• A 5xx on the legacy query() path now raises ServiceUnavailable, a RuntimeError (previously a ValueError) — a transient server failure is a runtime condition, not a bad value.
• The Water Data chunker's planner-floor error is Unchunkable (a RequestTooLarge subclass).
• Import the transport types / bases from dataretrieval / dataretrieval.exceptions, not from dataretrieval.waterdata.chunking.

The root catch (except DataRetrievalError) and ValueError / RuntimeError compatibility (by kind) are preserved.

Verification

• 477 passed / 2 skipped; ruff clean.
• Live API (legacy query() path): 404 → NotFoundError, 400 → BadRequestError, an over-long URL → URLTooLong (all DataRetrievalError + ValueError); a 200 is unaffected.
• All 21 example notebooks execute end-to-end against the live API (227/227 code cells, 0 errors), exercising the modern waterdata path.

Out of scope (proposed follow-ups)

• nadp / streamstats still raise httpx.HTTPStatusError — a one-line swap each to _raise_for_status, but it changes their public error type.
• nldi's manual non-200 ValueError and nwis._parse_json_or_raise's HTML-detection ValueError aren't rooted yet.
• waterdata._raise_for_non_200's catch-all for non-retryable 4xx stays a bare RuntimeError — load-bearing for the chunker's fatal-vs-resumable classifier; rooting it needs a dedicated ClientError(DataRetrievalError, RuntimeError) plus a chunker-classification review.

🤖 Generated with Claude Code