Repository navigation
Error Handling
Every error the SDK raises inherits from EeroException — here's the full tree, how the API's error catalogue selects the class, and how to handle them.
All exceptions are defined in src/eero/exceptions.py:
Exception
└── EeroException (.message, .envelope, .error_code, is_auth_error())
├── EeroAuthenticationException (.status_code) is_auth_error() → True
├── EeroRateLimitException (.status_code, .retry_after)
├── EeroNetworkException
├── EeroTimeoutException
├── EeroValidationException (.field) — client-side validation AND API 400 form errors
└── EeroAPIException (.status_code)
├── EeroAccessDeniedException
├── EeroClientBlockedException
├── EeroNotFoundException (.resource_type, .resource_id)
├── EeroPremiumRequiredException (.feature)
└── EeroFeatureUnavailableException (.feature, .reason)
Every class is exported from the top-level eero package (from eero import EeroNotFoundException works), alongside the error catalogue helpers ErrorGroup, classify_error_code, and exception_for_error — see The error catalogue.
⚠️ Warning:EeroValidationExceptionis not a subclass ofEeroAPIException, even though the transport raises it for an API400carrying a form-error string. It derives fromEeroExceptiononly, because it is also the SDK's own client-side validation error (bad IP literal, bad header value, …). A handler that catches onlyEeroAPIExceptionwill not see an API validation error — catchEeroValidationExceptionexplicitly, or catchEeroException.
When the API answers with an error status, the SDK parses the body once and attaches the result to the exception — it does not paste the body into the message:
| Attribute | Type | Value |
|---|---|---|
err.envelope |
Optional[Dict[str, Any]] |
The raw, unmodified JSON response envelope ({"meta": {...}, ...}) when the body was a JSON object; None when the body was empty, not JSON, or when no response was received at all (EeroNetworkException, EeroTimeoutException, local EeroValidationException) |
err.error_code |
Optional[str] |
envelope["meta"]["error"] exactly as the API sent it, when present and a string; otherwise None
|
err.message / str(err)
|
str |
For an API error: the recognised catalogue string (trimmed, lowercased) when error_code is in the catalogue, or the fixed label unrecognised error string when it is absent, empty, or free text. EeroAPIException and its subclasses prefix this with API error <status>: . Never the body text, never the request URL |
from eero import EeroAPIException, EeroAuthenticationException, EeroNotFoundException
try:
await client.get_network(network_id="<network-id>")
except EeroAuthenticationException as err:
if err.error_code == "error.verification.required":
print("Finish the OTP flow first")
else:
print(f"Session rejected: {err.error_code}")
except EeroNotFoundException as err:
print(err.status_code, err.error_code) # 404, e.g. "error.network.not.found"
except EeroAPIException as err:
if err.envelope is not None:
print(err.envelope["meta"]) # the API's own error metadata, unmodifiedTwo exceptions also carry what the response said about timing and status, both optional and None when unknown:
| Attribute | On | Value |
|---|---|---|
err.status_code |
EeroAuthenticationException, EeroRateLimitException (every EeroAPIException subclass has it too) |
The HTTP status of the response. Always 401 on an authentication exception raised for a response, and the actual status on a rate-limit exception — error.rate.limit is classified as a rate limit on any status, so it is not always 429. None when the exception was raised locally, with no response (for example "No session token available") |
err.retry_after |
EeroRateLimitException |
The delay in seconds the server asked for in its Retry-After header: either delta-seconds, or an HTTP-date converted to the (non-negative) number of seconds from now. Either form is capped at one day (86400). None when the header was absent or in neither form. The SDK never sleeps or retries on it — it only reports it |
Both are keyword-only constructor arguments that default to None, so EeroAuthenticationException("msg") and EeroRateLimitException("msg", envelope=..., error_code=...) construct exactly as before.
Branch on error_code (or on the exception class), never on the message string — the message is a fixed, leak-safe label; error_code is what the API sent. The envelope is the API's exact response; the SDK does not rewrite or trim it.
The same rule applies to log output: the transport logs the parsed envelope through the redacting secure logger at DEBUG for every error status (plus a status-and-method-only ERROR line for statuses other than 401/404/429) and never the raw body text. See Logging and Security.
The API reports failures as {"meta": {"code": <status>, "error": "<string>"}}. The meta.error strings form a closed catalogue of dot-separated identifiers; the SDK keeps that catalogue in src/eero/errors.py, groups each string by meaning, and matches case-insensitively (surrounding whitespace trimmed). Some error responses omit meta.error, and some carry a free-text sentence instead — neither is in the catalogue, and the SDK treats both as "unrecognised".
| Export | What it does |
|---|---|
ErrorGroup (str, Enum) |
SESSION, SESSION_REFRESH, VERIFICATION, ACCESS_DENIED, NOT_FOUND, RATE_LIMIT, VALIDATION, PREMIUM, FEATURE_UNAVAILABLE, CLIENT_BLOCKED, DOMAIN
|
classify_error_code(error_code) -> Optional[ErrorGroup] |
The group a meta.error string belongs to, or None for None/empty/unrecognised/free-text input |
message_for_error_code(error_code) -> str |
The normalised catalogue string, or "unrecognised error string" (eero.errors only — not re-exported from the package root) |
exception_for_error(status_code, *, envelope, error_code, retry_after=None) -> EeroException |
Builds (does not raise) the exception the transport will raise for a non-2xx/3xx response, with envelope and error_code attached. status_code is attached to authentication and rate-limit exceptions, and retry_after to rate-limit exceptions (it is ignored for every other class) |
SESSION_ERRORS, VERIFICATION_ERRORS, … DOMAIN_ERRORS (FrozenSet[str]) |
The member strings of each group (eero.errors only) |
exception_for_error is the single place classification happens, and its precedence is fixed:
-
HTTP 401 →
EeroAuthenticationException, always, whatevermeta.errorsays. - Otherwise a string in a status-independent group —
PREMIUM,FEATURE_UNAVAILABLE,CLIENT_BLOCKED,RATE_LIMIT— selects its class regardless of HTTP status. - Otherwise the HTTP status selects the class:
403+error.access.denied→EeroAccessDeniedException; every404→EeroNotFoundException;429→EeroRateLimitException;400+ aVALIDATIONstring →EeroValidationException. - Everything else — every
DOMAINstring, any unrecognised or free-text string, a403/400that doesn't match above — isEeroAPIException.
An unrecognised or free-text meta.error never changes the class chosen by the status and never raises on its own; it is carried through as error_code on whatever exception is raised.
ErrorGroup |
Catalogue strings | Class raised | Notes |
|---|---|---|---|
SESSION |
error.session.expired, error.session.invalid, error.session.revoked
|
EeroAuthenticationException |
Terminal. When the refresh endpoint returns one of these, stored credentials are cleared — as they are for any 401 from refresh whose string is not in VERIFICATION or SESSION_REFRESH, including unrecognised/absent strings |
SESSION_REFRESH |
error.session.refresh |
EeroAuthenticationException — only if the refresh fails |
On a 401 the transport calls refresh_session() and replays the request once; credentials are never cleared by this string. See Authentication
|
VERIFICATION |
error.verification.required, .invalid, .expired, .failure, .blocked, error.login.unknown, error.login.blocked, error.too.many.resends, error.email.unverified
|
EeroAuthenticationException |
The account is mid-verification or blocked from completing login. Never clears stored credentials |
ACCESS_DENIED |
error.access.denied |
EeroAccessDeniedException (on 403) |
Authenticated but not permitted. Not an auth error; credentials kept |
NOT_FOUND |
error.network.not.found, error.eero.no_serial_found, error.software_keys.not_found
|
EeroNotFoundException |
Every 404 raises this class, with or without a recognised string |
RATE_LIMIT |
error.rate.limit |
EeroRateLimitException |
Also raised for any HTTP 429 |
VALIDATION |
error.form.errors, error.form.email.unavailable, error.form.phone.unavailable, error.form.email.malformed, error.form.phone.malformed, error.invites.format.faulty, error.invalid.user.role, error.reservation.ip.invalid, error.network.multistaticipv2.wan_ip_not_in_range
|
EeroValidationException (on 400) |
field == "request"; envelope carries the API's detail. Not an EeroAPIException — see the warning above |
PREMIUM |
error.premium.user_not_subscribed, error.partner.unavailable
|
EeroPremiumRequiredException |
Any status |
FEATURE_UNAVAILABLE |
error.eero.offline, error.network.unavailable, error.eero.not.capable, error.eero.deactivated, error.eero.owned_by_organization, error.eero.wifibackup.as.gateway, error.eero.already.owned, error.eero.needs.reset
|
EeroFeatureUnavailableException |
Any status |
CLIENT_BLOCKED |
error.app.version.blocked |
EeroClientBlockedException |
Any status — the API refuses this client version |
DOMAIN |
error.reservation.failed, error.assignment.ip.unavailable, error.assignment.port.unavailable, error.forward.failed, error.backup.access.point.ssid.already.exists, error.backup.access.point.ssid.conflict, error.max.number.of.backup.access.points.reached, error.invite.status.accepted/.rejected/.revoked/.expired, error.max.admins.reached, error.public_static_ip.reservation.error, error.network.transfer.recipient.unverified_phone/.unverified_email/.mismatched_phone/.mismatched_email/.ambiguous, error.user.amazon_login.exists, error.user.amazon_login.email.unavailable, error.software_keys.already_used, error.stripe.card.incorrect_number/.expired/.incorrect_cvc/.incorrect_zip/.declined/.processing_error, error.stripe.coupon.inappropriate/.invalid/.missing, encryptme.error.email.exists/.email.invalid/.creation.failed
|
EeroAPIException |
Stay generic; branch on error_code
|
from eero import ErrorGroup, classify_error_code
classify_error_code("Error.Session.Expired") # ErrorGroup.SESSION (case-insensitive)
classify_error_code("Something went wrong") # None — free text
classify_error_code(None) # None| Exception | When it's raised | Extra attributes |
|---|---|---|
EeroException |
Base class — not raised directly by the SDK | — |
EeroAuthenticationException |
Every HTTP 401 (after the refresh-and-replay attempt, when applicable); also raised locally when an auth operation needs a session token and none is present |
status_code (Optional[int]; 401 from a response, None when raised locally) |
EeroRateLimitException |
HTTP 429, or error.rate.limit on any status |
status_code (Optional[int]), retry_after (Optional[float], seconds, from Retry-After) |
EeroNetworkException |
Any aiohttp.ClientError (DNS failure, connection reset, TLS error, etc.) |
— (envelope is None) |
EeroTimeoutException |
asyncio.TimeoutError (request exceeded the configured timeout) |
— (envelope is None) |
EeroAPIException |
Blocked redirect (3xx), oversized response body, a 2xx body that is not valid UTF-8, not valid JSON, or not a JSON object, and any error status not claimed by a subclass below — including every DOMAIN string and every unrecognised string |
status_code (Optional[int]) |
EeroAccessDeniedException |
HTTP 403 with error.access.denied
|
status_code |
EeroClientBlockedException |
error.app.version.blocked on any status |
status_code |
EeroNotFoundException |
Every HTTP 404 |
status_code, resource_type, resource_id (both None when built by the transport, which has no resource context; set when constructed directly) |
EeroPremiumRequiredException |
A PREMIUM string on any status |
status_code, feature (the generic default when built by the transport) |
EeroFeatureUnavailableException |
A FEATURE_UNAVAILABLE string on any status |
status_code, feature (the error_code), reason (the message) |
EeroValidationException |
(a) Locally, before any network call: id_from_url() given an empty/non-string ID; set_session_token() given an empty/non-string token; an accept_language or any other header value that is not printable ASCII; a caller-supplied X-User-Token / Cookie / Authorization header; allow_redirects=True; more than one body carrier on one request; an invalid cadence on the data-usage methods; an empty serial / version on get_ouicheck; the DNS write methods given a malformed IP literal, an address of the wrong family, a zone-scoped address, more than 2 servers for one family, an unrecognised DNS mode, or mode="custom" without servers. (b) From the API: HTTP 400 with a VALIDATION string |
field (the offending argument locally; "request" from the API) |
The legacy constructors still work for direct construction — EeroNotFoundException(resource_type, resource_id), EeroPremiumRequiredException(feature), EeroFeatureUnavailableException(feature, reason), EeroValidationException(field, message) — and each of those classes also has a from_response(message, *, envelope=None, error_code=None) classmethod (plus status_code= on the three EeroAPIException subclasses) that the transport uses when it has no resource/feature/field context. EeroAuthenticationException and EeroRateLimitException have no from_response: the transport passes status_code= (and retry_after=) to their ordinary constructors.
What BaseAPI._request() (via exception_for_error) does for each response:
| HTTP status | Exception raised | Notes |
|---|---|---|
200–299
|
(none — success) |
204 or an empty body returns {}. A body that is not valid UTF-8, not valid JSON, or valid JSON that is not an object (a list, string, number, true/false or null) is an invalid response and raises EeroAPIException with the status and a fixed message — the body text is never included |
300–399
|
EeroAPIException |
Redirects are never followed (allow_redirects=False, not overridable) and are always rejected, to stop the session token leaking to another host |
400 |
EeroValidationException if meta.error is a VALIDATION string, else EeroAPIException
|
field == "request"; API detail in envelope
|
401 |
EeroAuthenticationException (status_code == 401) |
Always, whatever the string. error.session.refresh first triggers a transparent refresh + single replay; the exception is raised only if there's no refresh hook or the refresh fails. Stored credentials are cleared whenever the refresh endpoint answers 401 with anything other than a VERIFICATION or SESSION_REFRESH string (a SESSION string, any other recognised group, or an unrecognised/absent string) |
403 |
EeroAccessDeniedException with error.access.denied, else EeroAPIException
|
Not an auth error; credentials kept |
404 |
EeroNotFoundException |
Always — with a catalogue string, a free-text sentence, or no meta.error at all |
429 |
EeroRateLimitException (status_code == 429, retry_after from the Retry-After header) |
See Caching and Rate Limits |
any status with a PREMIUM / FEATURE_UNAVAILABLE / CLIENT_BLOCKED / RATE_LIMIT string (except 401) |
the group's class | Status-independent groups; a RATE_LIMIT string keeps the actual status_code and also reads Retry-After
|
| everything else |
EeroAPIException (status_code=<actual>) |
The generic fallback, error_code set when present. An error body that is not valid UTF-8 is decoded with replacement characters, so the status mapping above still applies and the exception is the one the status selects (envelope is None unless the body still parses as a JSON object) |
response body > MAX_RESPONSE_BYTES
|
EeroAPIException |
Raised mid-stream, before the body is fully buffered |
asyncio.TimeoutError |
EeroTimeoutException |
Request exceeded the timeout (see Configuration) |
aiohttp.ClientError |
EeroNetworkException |
Connection-level failures, wrapped with from err
|
What is retried before any of these reach you. Writes (POST/PUT/DELETE/PATCH) are never retried by the SDK. A GET that fails with EeroNetworkException, EeroTimeoutException, or a 5xx EeroAPIException is retried up to get_retries additional times (constructor option, default 0); 4xx and 429 are never retried. The exception you catch is the one from the final attempt. See Configuration.
Every EeroException has an is_auth_error() method so you can branch on "should I re-authenticate?" without checking exception types one by one:
try:
await client.get_networks()
except EeroException as err:
if err.is_auth_error():
await client.login("you@example.com")
await client.verify(input("Code: "))
else:
raise-
EeroAuthenticationException.is_auth_error()— alwaysTrue. This is the only class the transport raises for a 401, so in practice it is the only one for which the method returnsTrue. -
EeroAPIException.is_auth_error()(inherited byEeroAccessDeniedExceptionand the other subclasses) —status_code == 401, which the transport never produces for these classes; it isFalsefor every 403/404/… includingEeroAccessDeniedException. - Every other class —
False.
A 403 is deliberately not an auth error: the session is valid, the account simply isn't allowed to do that.
⚠️ Warning: Every exception in this SDK ends inException, neverError. If you're searching the codebase or your own traceback for a name and coming up empty, check for these common wrong guesses:
Wrong (doesn't exist) Right EeroErrorEeroExceptionEeroAuthError/EeroAuthenticationErrorEeroAuthenticationExceptionEeroAPIErrorEeroAPIExceptionEeroRateLimitErrorEeroRateLimitExceptionEeroTimeoutErrorEeroTimeoutExceptionEeroForbiddenException/EeroForbiddenErrorEeroAccessDeniedExceptionThese
*Errornames have never existed in any release — earlier versions of this wiki documented them incorrectly, so code copied from it will fail at import. If you're upgrading from a pre-v2.0 release and yourexceptclauses reference the deleted model classes, see Migration.
from eero import EeroException
try:
await client.get_networks()
except EeroException as err:
print(f"Eero API call failed: {err.error_code or err.message}")from eero import (
EeroAccessDeniedException,
EeroAPIException,
EeroAuthenticationException,
EeroNotFoundException,
EeroRateLimitException,
EeroValidationException,
)
try:
await client.get_devices()
except EeroAuthenticationException as err:
print(f"Session rejected ({err.error_code}) — need to log in again")
except EeroAccessDeniedException:
print("This account may not do that on this network")
except EeroNotFoundException:
print("No such network")
except EeroRateLimitException:
print("Rate limited — back off")
except EeroValidationException as err:
print(f"The API rejected the request: {err.error_code}") # not an EeroAPIException
except EeroAPIException as err:
print(f"API error {err.status_code}: {err.error_code}")from eero import EeroAPIException
try:
await client.create_reservation(reservation_data={...})
except EeroAPIException as err:
if err.error_code == "error.assignment.ip.unavailable":
... # pick another address
else:
raisefrom eero import EeroAuthenticationException
try:
await client.get_account()
except EeroAuthenticationException:
await client.login("you@example.com")
await client.verify(input("Code: "))
await client.get_account() # retryimport asyncio
from eero import EeroNetworkException, EeroRateLimitException, EeroTimeoutException
async def get_networks_with_retry(client, max_attempts: int = 5):
for attempt in range(max_attempts):
try:
return await client.get_networks()
except (EeroRateLimitException, EeroTimeoutException, EeroNetworkException):
if attempt == max_attempts - 1:
raise
await asyncio.sleep(2 ** attempt)import asyncio
from eero import EeroRateLimitException
async def get_networks_once_after_rate_limit(client):
try:
return await client.get_networks()
except EeroRateLimitException as err:
if err.retry_after is None:
raise # the server gave no usable hint
await asyncio.sleep(min(err.retry_after, 60))
return await client.get_networks()Only reads are safe to repeat like this. The SDK never retries a write, and neither should this pattern: read the state back first.
from eero import EeroFeatureUnavailableException, EeroPremiumRequiredException
try:
await client.get_premium_status()
except EeroPremiumRequiredException as err:
print(f"Needs an Eero Plus subscription ({err.error_code})")
except EeroFeatureUnavailableException as err:
print(f"Not available on this network: {err.error_code}")- Migration — the v8.0.0 error-class changes and how to update handlers
- Authentication — 401 semantics, refresh-and-replay, credential clearing
-
Caching and Rate Limits — avoiding
EeroRateLimitExceptionin the first place - Configuration — request timeouts and the GET retry policy
- Troubleshooting — common issues & fixes
-
Logging and Security —
SecureLoggerAdapterand safe debug logging of failed requests
eero-api — unofficial async Python client for the Eero cloud API. Not affiliated with or endorsed by Eero.
This wiki is generated from wiki/ in the main repository — edit there, not here. · MIT License