refactor(errors): introduce DataRetrievalError as a unified request-error root

An HTTP failure surfaced as a different exception type depending on which
module made the request:

  - legacy query() (wqp, nwis, ngwmn, nldi): ValueError, or NoSitesError(Exception)
  - waterdata: RateLimited / ServiceUnavailable (RuntimeError),
    RequestTooLarge (ValueError), ChunkInterrupted (RuntimeError)
  - nadp / streamstats: bare httpx.HTTPStatusError

so no single `except` clause could catch "any dataretrieval request failure."

Add a shared base class, dataretrieval.utils.DataRetrievalError, and root the
existing exceptions on it. Unification is at the root only -- each exception
keeps the built-in type it has always raised, so the change is backward
compatible:

  - New typed errors for the legacy query() path -- BadRequestError (400),
    NotFoundError (404), RequestTooLargeError (414), ServiceUnavailableError
    (5xx) -- each subclassing (DataRetrievalError, ValueError). Messages and the
    set of statuses query() raises on are unchanged, and every type is still a
    ValueError, so existing `except ValueError` handlers keep working.
  - Consolidate query()'s inline status-code ladder into a reusable
    _raise_for_status() helper.
  - NoSitesError now subclasses DataRetrievalError (was Exception).
  - waterdata's RateLimited / ServiceUnavailable / RequestTooLarge /
    ChunkInterrupted gain DataRetrievalError as an additional base (additive --
    they remain RuntimeError / ValueError, so the chunker's isinstance
    classification and all existing handlers are unaffected).

Callers can now write `except dataretrieval.DataRetrievalError` to handle a
failure from any module while keeping the historical built-in types.

Out of scope (follow-ups): nadp/streamstats still raise httpx.HTTPStatusError;
nldi's manual non-200 ValueError and nwis._parse_json_or_raise's HTML-detection
ValueError are not yet rooted; waterdata's _raise_for_non_200 catch-all for
non-retryable 4xx stays a bare RuntimeError (load-bearing for the chunker's
fatal-vs-resumable classifier).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: thodson-usgs

dataretrieval/utils.py

@@ -270,14 +270,79 @@ def __repr__(self) -> str:
                         data_list.append(data)  # append results to list"""
 
 
-def _url_too_long_error(detail: str) -> ValueError:
-    return ValueError(
+class DataRetrievalError(Exception):
+    """Base class for errors raised when a request to a USGS or EPA web
+    service fails.
+
+    Every service module (``nwis``, ``wqp``, ``waterdata``, ``nldi``, ...)
+    raises a subclass of this when a request fails, so a caller can handle any
+    request failure uniformly::
+
+        try:
+            df, md = dataretrieval.wqp.get_results(...)
+        except dataretrieval.DataRetrievalError:
+            ...
+
+    Subclasses also inherit from the built-in exception this package has
+    historically raised for the same condition (e.g. :class:`BadRequestError`
+    is also a :class:`ValueError`), so existing ``except ValueError`` handlers
+    keep working unchanged.
+    """
+
+
+class BadRequestError(DataRetrievalError, ValueError):
+    """The service rejected the request parameters (HTTP 400)."""
+
+
+class NotFoundError(DataRetrievalError, ValueError):
+    """The requested resource was not found; often an empty query (HTTP 404)."""
+
+
+class RequestTooLargeError(DataRetrievalError, ValueError):
+    """The request URL was too long for the service (HTTP 414, or rejected
+    client-side before it was sent)."""
+
+
+class ServiceUnavailableError(DataRetrievalError, ValueError):
+    """The service is down or returned a server error (HTTP 5xx)."""
+
+
+def _url_too_long_error(detail: str) -> RequestTooLargeError:
+    return RequestTooLargeError(
         "Request URL too long. Modify your query to use fewer sites. "
         f"{detail}. Pseudo-code example of how to split your query: "
         f"\n {_URL_TOO_LONG_EXAMPLE}"
     )
 
 
+def _raise_for_status(response: httpx.Response) -> None:
+    """Raise a typed :class:`DataRetrievalError` for an unsuccessful response.
+
+    Centralizes the HTTP-status-to-exception mapping for the shared
+    :func:`query` path so every legacy service module (``wqp``, ``nwis``,
+    ``ngwmn``, ``nldi``) surfaces request failures the same way. A successful
+    response returns ``None``. The raised types are also :class:`ValueError`
+    subclasses, preserving this module's historical contract.
+    """
+    status = response.status_code
+    if status == 400:
+        raise BadRequestError(
+            f"Bad Request, check that your parameters are correct. URL: {response.url}"
+        )
+    elif status == 404:
+        raise NotFoundError(
+            "Page Not Found Error. May be the result of an empty query. "
+            + f"URL: {response.url}"
+        )
+    elif status == 414:
+        raise _url_too_long_error(f"API response reason: {response.reason_phrase}")
+    elif 500 <= status < 600:
+        raise ServiceUnavailableError(
+            f"Service Unavailable: {status} {response.reason_phrase}. "
+            + f"The service at {response.url} may be down or experiencing issues."
+        )
+
+
 def query(url, payload, delimiter=",", ssl_check=True):
     """Send a query.
 
@@ -321,30 +386,15 @@ def query(url, payload, delimiter=",", ssl_check=True):
     except httpx.InvalidURL as exc:
         raise _url_too_long_error(f"httpx rejected the URL client-side: {exc}") from exc
 
-    if response.status_code == 400:
-        raise ValueError(
-            f"Bad Request, check that your parameters are correct. URL: {response.url}"
-        )
-    elif response.status_code == 404:
-        raise ValueError(
-            "Page Not Found Error. May be the result of an empty query. "
-            + f"URL: {response.url}"
-        )
-    elif response.status_code == 414:
-        raise _url_too_long_error(f"API response reason: {response.reason_phrase}")
-    elif 500 <= response.status_code < 600:
-        raise ValueError(
-            f"Service Unavailable: {response.status_code} {response.reason_phrase}. "
-            + f"The service at {response.url} may be down or experiencing issues."
-        )
+    _raise_for_status(response)
 
     if response.text.startswith("No sites/data"):
         raise NoSitesError(response.url)
 
     return response
 
 
-class NoSitesError(Exception):
+class NoSitesError(DataRetrievalError):
     """Custom error class used when selection criteria returns no sites/data."""
 
     def __init__(self, url):

dataretrieval/waterdata/chunking.py

@@ -66,7 +66,7 @@
 import pandas as pd
 from anyio.from_thread import start_blocking_portal
 
-from dataretrieval.utils import HTTPX_DEFAULTS
+from dataretrieval.utils import HTTPX_DEFAULTS, DataRetrievalError
 
 from . import _progress
 from .filters import (
@@ -383,7 +383,7 @@ def _passthrough_result(
     return frame, response
 
 
-class _RetryableTransportError(RuntimeError):
+class _RetryableTransportError(DataRetrievalError, RuntimeError):
     """
     Base for typed HTTP transport failures the chunker recognizes as
     transient.
@@ -435,7 +435,7 @@ class ServiceUnavailable(_RetryableTransportError):
     """
 
 
-class RequestTooLarge(ValueError):
+class RequestTooLarge(DataRetrievalError, ValueError):
     """
     No chunking plan fits the URL byte limit.
 
@@ -446,7 +446,7 @@ class RequestTooLarge(ValueError):
     """
 
 
-class ChunkInterrupted(RuntimeError):
+class ChunkInterrupted(DataRetrievalError, RuntimeError):
     """
     Base class for mid-stream chunk failures whose completed work is
     preserved and resumable.

tests/utils_test.py

@@ -42,6 +42,74 @@ def test_header(self):
         assert "user-agent" in response.request.headers
 
 
+class Test_error_taxonomy:
+    """The unified request-error hierarchy.
+
+    Every module's request failures are catchable as ``DataRetrievalError``,
+    while remaining backward-compatible with the built-in type each path
+    historically raised (``ValueError`` for the legacy ``query`` path,
+    ``RuntimeError`` for the waterdata retryable types).
+    """
+
+    @pytest.mark.parametrize(
+        "status, exc_name, match",
+        [
+            (400, "BadRequestError", "Bad Request"),
+            (404, "NotFoundError", "Page Not Found"),
+            (414, "RequestTooLargeError", "Request URL too long"),
+            (503, "ServiceUnavailableError", "Service Unavailable: 503"),
+        ],
+    )
+    def test_query_maps_status_to_typed_error(
+        self, httpx_mock, status, exc_name, match
+    ):
+        """``query`` maps each HTTP status family to a typed error that is both
+        a ``DataRetrievalError`` (new, unified) and a ``ValueError`` (the type
+        this path has always raised), with the message preserved."""
+        exc_cls = getattr(utils, exc_name)
+        url = "https://example.invalid/x"
+        httpx_mock.add_response(method="GET", url=f"{url}?a=1", status_code=status)
+        with pytest.raises(exc_cls, match=match) as excinfo:
+            utils.query(url, {"a": "1"})
+        assert isinstance(excinfo.value, utils.DataRetrievalError)
+        assert isinstance(excinfo.value, ValueError)  # backward compatibility
+
+    def test_query_failure_catchable_as_base(self, httpx_mock):
+        """A bare ``except DataRetrievalError`` catches a legacy query failure."""
+        url = "https://example.invalid/y"
+        httpx_mock.add_response(method="GET", url=f"{url}?a=1", status_code=400)
+        with pytest.raises(utils.DataRetrievalError):
+            utils.query(url, {"a": "1"})
+
+    def test_no_sites_error_is_data_retrieval_error(self):
+        """``NoSitesError`` joins the root (was a bare ``Exception``)."""
+        assert issubclass(utils.NoSitesError, utils.DataRetrievalError)
+        assert not issubclass(utils.NoSitesError, ValueError)  # unchanged
+
+    def test_waterdata_exceptions_share_the_root(self):
+        """waterdata's typed exceptions are ``DataRetrievalError`` too, so one
+        ``except`` clause spans the legacy and waterdata subsystems — while
+        keeping their historical ``RuntimeError``/``ValueError`` bases."""
+        from dataretrieval.waterdata.chunking import (
+            ChunkInterrupted,
+            RateLimited,
+            RequestTooLarge,
+            ServiceUnavailable,
+        )
+
+        for cls in (RateLimited, ServiceUnavailable, RequestTooLarge, ChunkInterrupted):
+            assert issubclass(cls, utils.DataRetrievalError)
+        assert issubclass(RateLimited, RuntimeError)
+        assert issubclass(ServiceUnavailable, RuntimeError)
+        assert issubclass(RequestTooLarge, ValueError)
+
+    def test_base_exported_at_top_level(self):
+        """Users can write ``except dataretrieval.DataRetrievalError``."""
+        import dataretrieval
+
+        assert dataretrieval.DataRetrievalError is utils.DataRetrievalError
+
+
 class Test_BaseMetadata:
     """Tests of BaseMetadata"""