home-assistant/core · error · UpdateFailed

Error while retrieving data: {err}

Error message

Error while retrieving data: {err}

What it means

UpdateFailed raised by the AirVisual coordinator when the IQAir/AirVisual API raises AirVisualError for any reason other than the explicitly-handled auth errors (InvalidKeyError, KeyExpiredError, UnauthorizedError raise ConfigEntryAuthFailed instead). It means the request reached the API but failed at the API/application level.

Source

Thrown at homeassistant/components/airvisual/coordinator.py:71

        """Get new data from the API."""
        if CONF_CITY in self.config_entry.data:
            api_coro = self._cloud_api.air_quality.city(
                self.config_entry.data[CONF_CITY],
                self.config_entry.data[CONF_STATE],
                self.config_entry.data[CONF_COUNTRY],
            )
        else:
            api_coro = self._cloud_api.air_quality.nearest_city(
                self.config_entry.data[CONF_LATITUDE],
                self.config_entry.data[CONF_LONGITUDE],
            )

        try:
            return await api_coro
        except (InvalidKeyError, KeyExpiredError, UnauthorizedError) as ex:
            raise ConfigEntryAuthFailed from ex
        except AirVisualError as err:
            raise UpdateFailed(f"Error while retrieving data: {err}") from err

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Check your AirVisual API plan usage — quota exhaustion is the most frequent cause; upgrade the plan or lengthen the polling interval.
2. Verify latitude/longitude in the config entry are valid numbers in range.
3. Confirm IQAir service status for transient 5xx errors.
4. Inspect the chained err text — it names the exact API error (e.g. 'over quota').
5. Update the pyairvisual library if the API contract changed.

def is_airvisual_update_failed(err: Exception) -> bool:
    return isinstance(err, UpdateFailed) and str(err).startswith("Error while retrieving data")

try:
    await coordinator.async_refresh()
except ConfigEntryAuthFailed:
    # key invalid/expired: fix the API key, not a retry problem
    raise
except UpdateFailed as err:
    # quota/5xx: back off before the next poll
    await asyncio.sleep(60)

When it happens

Trigger: nearest_city() (cloud) or the node-pro call raises AirVisualError: over quota (free tier limits), rate limiting, server 5xx, malformed request coordinates, or unavailable station data. Invalid/expired API keys take the auth path, not this one.

Common situations: Exceeding the free AirVisual API request quota (very common on the basic plan with default polling), temporary IQAir outages, or invalid lat/long values in the config entry.

Related errors

• System generated users cannot enable multi-factor auth modul
• update_error
• Failed to press {button} button.
• Failed to turn on {switch}.
• Failed to turn off {switch}.

AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/845c1a7bd2eda4a5. Report an issue: GitHub.