Skip to content

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, overloaded and upstream_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