{"record":{"id":"845c1a7bd2eda4a5","repo":"home-assistant/core","slug":"error-while-retrieving-data-err","errorCode":null,"errorMessage":"Error while retrieving data: {err}","messagePattern":"Error while retrieving data: (.+?)","errorType":"exception","errorClass":"UpdateFailed","httpStatus":null,"severity":"error","filePath":"homeassistant/components/airvisual/coordinator.py","lineNumber":71,"sourceCode":"        \"\"\"Get new data from the API.\"\"\"\n        if CONF_CITY in self.config_entry.data:\n            api_coro = self._cloud_api.air_quality.city(\n                self.config_entry.data[CONF_CITY],\n                self.config_entry.data[CONF_STATE],\n                self.config_entry.data[CONF_COUNTRY],\n            )\n        else:\n            api_coro = self._cloud_api.air_quality.nearest_city(\n                self.config_entry.data[CONF_LATITUDE],\n                self.config_entry.data[CONF_LONGITUDE],\n            )\n\n        try:\n            return await api_coro\n        except (InvalidKeyError, KeyExpiredError, UnauthorizedError) as ex:\n            raise ConfigEntryAuthFailed from ex\n        except AirVisualError as err:\n            raise UpdateFailed(f\"Error while retrieving data: {err}\") from err\n","sourceCodeStart":53,"sourceCodeEnd":72,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/airvisual/coordinator.py#L53-L72","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check your AirVisual API plan usage — quota exhaustion is the most frequent cause; upgrade the plan or lengthen the polling interval.","Verify latitude/longitude in the config entry are valid numbers in range.","Confirm IQAir service status for transient 5xx errors.","Inspect the chained err text — it names the exact API error (e.g. 'over quota').","Update the pyairvisual library if the API contract changed."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":"def is_airvisual_update_failed(err: Exception) -> bool:\n    return isinstance(err, UpdateFailed) and str(err).startswith(\"Error while retrieving data\")","tryCatchPattern":"try:\n    await coordinator.async_refresh()\nexcept ConfigEntryAuthFailed:\n    # key invalid/expired: fix the API key, not a retry problem\n    raise\nexcept UpdateFailed as err:\n    # quota/5xx: back off before the next poll\n    await asyncio.sleep(60)","preventionTips":["Match the polling interval to your AirVisual API plan limits (free tier is strict).","Monitor quota headers/error text for 'over quota' and lengthen the interval immediately.","Keep the API key valid — expired keys raise ConfigEntryAuthFailed, not this error, so classify before fixing."],"tags":["home-assistant","airvisual","iqair","rate-limit","cloud-api"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}