refactor(errors)!: a lean, idiomatic DataRetrievalError taxonomy

[thodson-usgs]

What

A small, idiomatic exception taxonomy: every request failure raises a subclass of DataRetrievalError, so one except dataretrieval.DataRetrievalError handles any of them. It adds only what the underlying httpx exceptions can't express.

DataRetrievalError(Exception)         # .status_code / .retry_after / .retryable
├─ HTTPError                  # .status_code — the server returned an error status
│   └─ TransientError         # .retry_after — retryable (429 / 5xx)
│       ├─ RateLimited        #   429
│       └─ ServiceUnavailable #   5xx
├─ RequestTooLarge            # the request can't fit
│   ├─ URLTooLong             #   414 / client-side over-long URL
│   └─ Unchunkable            #   the Water Data chunker can't split the call
├─ NetworkError               # no response: timeout / DNS / refused connection
└─ NoSitesError               # no-data on the legacy nwis path (see "no-data" below)

A single factory, dataretrieval.exceptions.error_for_status(...), maps a status to its type, and every request path routes through it — the legacy query path (nwis/wqp/nldi), the Water Data chunker, and nadp/streamstats — so a given status surfaces as the same type everywhere.

• Fatal 4xx → a generic HTTPError carrying .status_code (inspect the code rather than a class per code).
• Retryable (429 / 5xx) → RateLimited / ServiceUnavailable (both TransientError), carrying .retry_after.
• Domain failures → Unchunkable, URLTooLong (keeps the actionable "split your query" message on the legacy path).
• Connection-level failures (timeout, DNS, refused) → NetworkError, with the underlying httpx exception on __cause__.

Branch or retry without knowing the concrete type

Every DataRetrievalError exposes three read-anywhere fields — no isinstance, no httpx import:

• .status_code — the HTTP status, or None when the failure carried no response.
• .retry_after — seconds the server hinted (its Retry-After), or None.
• .retryable — True for the transient statuses (429 / 5xx) and connection failures; False otherwise.

for attempt in range(5):
    try:
        df, md = dataretrieval.waterdata.get_daily(...)
        break
    except dataretrieval.DataRetrievalError as e:
        if not e.retryable or attempt == 4:
            raise
        time.sleep(e.retry_after or 2 ** attempt)

A new "Handling errors" user-guide page documents these recipes (catch-all, retry-with-backoff, branch-on-status, resume a chunked call).

No-data is not an error

The modern getters (waterdata, wqp, nldi) return an empty DataFrame when nothing matches — check df.empty, don't catch. Only the deprecated nwis (waterservices) path still raises NoSitesError on no data.

Cross-process

The typed errors are picklable via the standard __getstate__/__setstate__ protocol, so they propagate cleanly back from multiprocessing / lithops workers. A ChunkInterrupted sheds its live .call resume handle across a process boundary (keeping the partial frame/response and counts), while in-process callers still get full exc.call.resume().

Breaking changes

• Request failures raise typed DataRetrievalError subclasses instead of bare ValueError / RuntimeError / httpx.HTTPStatusError. The tree roots only at DataRetrievalError(Exception) — no more builtin mixins, so except ValueError / except RuntimeError no longer catch them. This now also covers ChunkInterrupted (was a RuntimeError) and mid-pagination failures (were a bare RuntimeError). Catch DataRetrievalError (or a subclass).
• Connection failures are wrapped as NetworkError instead of raw httpx exceptions on the single-shot paths — catch NetworkError (or DataRetrievalError); the httpx exception is on __cause__.
• A fatal 4xx is an HTTPError (read .status_code); there are no per-code exception types.

Verification

ruff clean (pre-commit hooks). mypy --strict and the full pytest suite are re-run by CI on push. The taxonomy was previously exercised green locally: typed errors round-trip through pickle / deepcopy (including ChunkInterrupted with real partial data and NetworkError); every type exposes .status_code/.retry_after/.retryable uniformly; async chunked requests resume after a transient interruption (from both a sync caller and inside a running event loop). Adds a dataretrieval.exceptions API reference page, a "Handling errors" user guide, and a NEWS.md entry.

🤖 Generated with Claude Code

[thodson-usgs]

Please address my suggestions.

[thodson-usgs]

don't worry about long-standing callers here. We only recently introduced chunking. You can probably omit historical explanation. We want to jump straight to the longterm solution here.

[thodson-usgs]

Similarly, the documentation should focus on the current implementation. Not what was done previously

[thodson-usgs]

Double check, but we might omit RuntimeError, since this PR should implement the longterm solution.

[thodson-usgs]

can we simplify the wording here. Please copy edit.

[thodson-usgs]

Is it cleaner or simpler to handle these as DataRetrievalError also?

[thodson-usgs]

be sure this is absolutely necessary for the implementation. It smells fish.

[thodson-usgs]

Go ahead and add a deprecation worning on NoSitesError

[thodson-usgs]

In general, are you sure we treat nodata as an error? I thought the correct pattern was to return an empty data frame.