Handle PACKAGE_NOT_PAID_FOR API error gracefully

[lackas]

Since late March 2026, Viessmann's API returns PACKAGE_NOT_PAID_FOR (HTTP 402) for some users when fetching device features. This affects new installations across multiple countries (Germany, Poland, Ireland — see home-assistant/core#167367 and Viessmann community thread).

Previously, this response lacked a "data" key and triggered PyViCareInvalidDataError, crashing the entire integration setup in Home Assistant.

Approach:

• New PyViCareNotPaidForError exception, raised when the API returns errorType: PACKAGE_NOT_PAID_FOR
• In ViCareCachedService, this is caught separately from other API errors:
  • If a stale cache exists (existing users experiencing a transient block), return the cached data
  • If no cache exists (new users), re-raise as PyViCareNotSupportedFeatureError

The re-raise as PyViCareNotSupportedFeatureError is a deliberate choice: HA already catches this exception in ~10 places to skip unsupported features. This means no HA-side changes are needed — the integration will set up cleanly but with zero entities for affected users, rather than crashing during platform setup.

I considered keeping PyViCareNotPaidForError all the way through, but that would require changes in every is_supported() call path in HA. The distinct exception still exists at the library level for anyone who needs to distinguish "not paid" from "not supported" in their own code.

[CFenner]

Usually we note in the exception which feature is unavailable, can you bring that in here somehow?

[lackas]

The 402 response from the API looks like this (from home-assistant/core#167367):

{
  "viErrorId": "00-d74916d71b5c410ddb3878970190f1ce-...",
  "errorType": "PACKAGE_NOT_PAID_FOR",
  "message": "",
  "extendedPayload": {
    "monetization": "User doesn't have access to the dan..."
  }
}

It's the bulk /features/ endpoint that returns 402 — there's no per-feature granularity in the response, just a generic monetization message in extendedPayload. That's what we're currently putting into the exception message.

Without this fix, the response falls through to PyViCareInvalidDataError (no "data" key), which crashes HA during platform setup.

The reason I convert to PyViCareNotSupportedFeatureError in the cached service: the HA integration catches that exception in 40 places across 10 files. Propagating a new PyViCareNotPaidForError to HA would require duplicating all of that handling with very little benefit — when the API blocks the entire features endpoint, the integration is non-functional anyway. This way it degrades gracefully with no HA-side changes needed.

Happy to adjust the exception message or structure if you have something specific in mind.