Errors¶
A query's errors derive from WaterOGCAPIError, in water_ogcapi.exceptions. Other
exceptions keep their Python types: to_arrow() raises ValueError, a pyarrow error,
or a ModuleNotFoundError without the arrow extra, and a CQL2-JSON filter that JSON
cannot encode raises TypeError.
| Exception | Raised when | Carries |
|---|---|---|
ValidationError |
Caller input is invalid, before any page request; a ValueError |
A message naming the valid options |
ServiceError |
A request fails: an error status, a redirect, a malformed body | status, url, attempts, retry_after |
RateLimitError |
A 429 outlasts the retries, a ServiceError |
remaining, plus the above |
PaginationError |
Page requests of a traversal fail | failures, checkpoint |
PartialResultsError |
collect() lost a page after others arrived |
result, plus the above |
Every URL an error holds has its credential query parameters masked, and WaterData
sends the key only in a header.
Input errors¶
ValidationError names what went wrong and, where the set is finite, the valid options:
from water_ogcapi import WaterData
from water_ogcapi.exceptions import ServiceError, ValidationError
wd = WaterData()
try:
wd.collect("monitoring-location")
except ValidationError as err:
print(str(err)[:160])
Service errors¶
A failed request raises ServiceError with the status and the URL as sent. attempts
above 1 means the transport retried first:
try:
wd.item("monitoring-locations", "USGS-not-a-site")
except ServiceError as err:
print(err.status, err.attempts, err.url)
Failures during a traversal¶
A page request that fails inside iter_pages() raises PaginationError once every page
that arrived has been yielded. failures holds one ServiceError per failed request,
and checkpoint, when not None, resumes the query with iter_pages(resume=...).
collect() raises PartialResultsError when a page fails after at least one arrived.
Its result is a QueryResult of the pages that arrived, with completeness
limited, and collect(resume=err.result) sends only the requests still pending. A
PaginationError from collect() means no page arrived, and its checkpoint resumes
the query. The pattern, with one retry:
from water_ogcapi.exceptions import PaginationError, PartialResultsError
QUERY = {"monitoring_location_id": "USGS-01646500", "datetime": "2025-01-01/2025-01-31"}
try:
result = wd.collect("daily", params=QUERY)
except PartialResultsError as err:
result = wd.collect("daily", resume=err.result)
except PaginationError as err:
if err.checkpoint is None:
raise
result = wd.collect("daily", resume=err.checkpoint)
print(result.pagination.completeness)
wd.close()
The cache, quota, and resume notebook runs this against a transport that fails one request on purpose.