Errors and retries¶
Every error the SDK raises derives from StormloreError.
| Error | When |
|---|---|
MissingApiKeyError |
No key given and WXCHANGE_API_KEY unset or blank |
MissingExtraError |
A feature needs an extra that is not installed (stormlore[xarray]) |
UnknownZipError |
A ZIP code given as a place does not exist |
ZipLookupForbiddenError |
The key may not look up ZIP codes (read:observations), as a place or with client.zips |
ConnectionError |
The API could not be reached, or did not answer within timeout |
APIError |
The API answered with an error (subclasses below) |
APIError carries code (the API's machine-readable code), message, http_status,
request_id (quote it when asking for help) and attempts (requests sent, retries
included). Its subclasses follow the API's codes:
| Code | Error |
|---|---|
invalid_request, invalid_datetime_format, invalid_encoding, limit_out_of_range |
InvalidRequestError |
zips_too_many, zips_too_large (413) |
ZipsTooManyError (count), ZipsTooLargeError (both InvalidRequestError) |
unauthorized, and the gateway's invalid_token / missing_token |
UnauthorizedError |
forbidden |
ForbiddenError |
subscribe_required |
SubscribeRequiredError (model_id) |
payment_required |
PaymentRequiredError |
model_not_found, parameter_not_found, run_not_found, step_not_found |
ModelNotFoundError, ParameterNotFoundError, RunNotFoundError, StepNotFoundError (all NotFoundError) |
point_out_of_bounds |
PointOutOfBoundsError |
datetime_out_of_range |
DatetimeOutOfRangeError |
datetime_in_gap |
DatetimeInGapError |
observation_not_found, observation_source_not_found, advisory_not_found |
ObservationNotFoundError, ObservationSourceNotFoundError, AdvisoryNotFoundError (all NotFoundError) |
advisories_unavailable, zips_unavailable |
AdvisoriesUnavailableError, ZipsUnavailableError |
rate_limited (or any 429) |
RateLimitError (retry_after) |
key_cap_exceeded (429) |
KeyCapExceededError (a RateLimitError; cap is "<used>/<limit>" when sent) |
loading, overloaded, upstream_unavailable |
LoadingError, OverloadedError, UpstreamUnavailableError (all ServiceUnavailableError) |
internal_error |
InternalServerError |
A code the SDK does not know yet picks its class by HTTP status (401 UnauthorizedError,
403 ForbiddenError, 429 RateLimitError, 502/503 ServiceUnavailableError) and keeps
its code; under any other status it raises a plain APIError. A 502 or 503 whose body is not
the API's (a proxy's error page) raises ServiceUnavailableError with code None.
from stormlore import Client, ModelNotFoundError, RateLimitError
client = Client() # reads WXCHANGE_API_KEY
try:
client.forecast.point("gfz", (41.26, -95.94), "temperature_2m")
except ModelNotFoundError as err:
print(err.message, err.request_id)
except RateLimitError as err:
print(f"slow down: retry in {err.retry_after} s")
Retries¶
Every operation in the SDK is a read, so sending one again cannot apply anything twice. The client retries, by itself:
- a failure to connect (the request never left);
- 502 and 503, including
loading,overloadedandupstream_unavailable; - 429, only when the API says how long to wait (
Retry-After). A key that has spent its monthly cap (KeyCapExceededError) is never retried: it lifts when the cap is raised or the month turns.
It does not retry a 504 (the query ran past the API's 30 s budget; sending it again
doubles the load), a response that did not arrive within timeout, or any other 4xx.
When the API sends Retry-After (on a 429 or a 503), the client waits that long.
Otherwise it waits 0.5 s, 1 s, 2 s (each jittered by up to half either way). At most
max_retries retries (3 by default), and at most 20 s of waiting per call: a
Retry-After that does not fit in what is left raises at once rather than sleeping
past it. When retries run out, the last error is raised with attempts set.
client = Client(max_retries=0) # no retries at all
client = Client(timeout=60) # seconds to wait for each response