interventions[] on a capability = it's blocked. The capability exists but can't be used until the user takes action
Most common: authentication-required → resolve with PUT /devices/{id}/connect (re-auth flow)
subscription-upgrade-required → user needs a plan upgrade, you can't resolve this via API
Always iterate interventions[] and drive your UI from the id — this table shows every possible value and how to fix it
Quick reference of intervention codes you may encounter and how to resolve them.
Vehicles
General (any car you connect)
Intervention
When you see it
Resolution
home-location-required
home-location capability is not set.
Set it via PUT /v1/users/{userId}/devices/{deviceId}/home-location. Send real latitude/longitude — they drive at-home detection and gate solar-aware charging. Omitting them defaults to 0,0, which clears this intervention but leaves the vehicle permanently "not at home". Address fields (city/postalCode/street) are informational only. Details: home-location capability.
connector-type-required
'connector-type" capability is not set.
Set it via PUT /v1/users/{userId}/devices/{deviceId}/connector-type.
location-not-available
Vehicle location data is not available (e.g., vendor does not provide location). Shown on the location-detection capability.
Informational only — no action required. This intervention does not block device control. Note: without location data the system cannot determine whether the vehicle is at its home location, so the vehicle may be controlled even when away from home (e.g., at a public charging station).
VW CCO
Intervention
When you see it
Resolution
add-charging-location-required
Charging location not set.
Set it via PUT /v1/users/{userId}/devices/{deviceId}/add-charging-location
Tesla Official
Intervention
When you see it
Resolution
certificate-required
Certificate is not installed.
Resolve via PUT /v1/users/{userId}/devices/{deviceId}/install-certificate.
authentication-required
OAuth/auth fails or needs re-authentication.
Resolve via PUT /v1/users/{userId}/devices/{deviceId}/connect.
missing-scopes-required
Required scopes are missing.
Resolve via PUT /v1/users/{userId}/devices/{deviceId}/set-scopes.
Heat Pumps
Bosch/Buderus
Intervention
When you see it
Resolution
approval-required
Contract status is not active during onboarding.
Resolves automatically, once the contract is active; the intervention is removed automatically.
Offline >= 5 days
Intervention
When you see it
Resolution
authentication-required
Device is offline >= 5 days.
Resolve by re-authenticating (PUT /v1/users/{userId}/devices/{deviceId}/connect).
Electric Meters
Shelly (legacy)
Intervention
When you see it
Resolution
measurement-purpose-required
Measurement purpose is not confirmed.
Setup stays incomplete on creation until you confirm it.
Resolve via PUT /v1/users/{userId}/devices/{deviceId}/measurement-purpose with purpose set to gridMeter or pvProduction.
Battery operating mode
Intervention
When you see it
Resolution
smart-price-control-enabled
Shown on the operation-mode capability when the home's battery Smart Price Control automation is active. Manual mode changes are blocked while Smart Price Control is running.
Disable battery Smart Price Control for the home (via automation settings / vendor app), then retry the PUT.
control-permission-required
Shown on the operation-mode capability when clever-PV is not (yet) permitted to control the battery — the control-permission state is forbidden or pending. PUTs to operation-mode fail with 400 while this intervention is present.
Resolve via PUT /v1/users/{userId}/devices/{deviceId}/control-permission with { "request": "allow" }. SigEnergy: takes effect immediately. Fronius: the user receives a verification e-mail and must confirm it — the state stays pending (and the intervention remains) until confirmed.
Target Charging (Cars & Wallboxes)
Intervention
When you see it
Resolution
target-charging-setup-required
Shown on the target-charging capability when the EV's battery capacity or consumption is not configured (null or <= 0). Both values are required before target charging can be enabled.
Set both values: PUT /v1/users/{userId}/devices/{deviceId}/battery-capacity with { "batteryCapacity": <Wh> } and PUT /v1/users/{userId}/devices/{deviceId}/consumption with { "consumption": <Wh/km> }. The intervention clears automatically on the next read once both values are positive.
How target-charging-setup-required works
Why it exists. Target charging plans how much energy must flow into the vehicle by a given time. To translate the configured target (targetWh, targetSoC) into a concrete charge plan, the system needs the EV's battery capacity (Wh) and its energy consumption. Without both values a plan cannot be computed, so the capability is blocked.
Where the values live. Both values are stored per device: for a car on its charging settings, for a wallbox on the wallbox itself. They are set via the battery-capacity and consumption capabilities. A value counts as "set" only if it is greater than 0.
What is blocked — and what is not. The intervention only blocks enabling target charging, i.e. a PUT /v1/users/{userId}/devices/{deviceId}/target-charging with "enabled": true while it is currently disabled. That request fails with 422 (ConnectApiProblemDetails, errorCode: "interventionFound"; the detail text names the intervention id). Everything else still works while the intervention is present:
GET still returns the capability with the full plan data.
Disabling ("enabled": false) is never blocked.
Updating plan parameters (targetWh, executionTime, weekDays, …) without flipping enabled from false to true is not blocked either.
If the home additionally lacks the required subscription, subscription-upgrade-required takes precedence and the enable attempt fails with 402 instead.
Lifecycle. The intervention is computed at read time on every request — it is never persisted. There is no separate "resolve" call: once both values are positive, the next GET no longer includes it and enabling succeeds.
Diagnosing which value is missing. The GET response of target-charging includes the current batteryCapacity and consumption as nullable fields in data, so you can tell which of the two still needs to be set.
General Onboarding
Intervention
When you see it
Resolution
authentication-required
Authentication issues with the device.
Resolve by re-authenticating (PUT /v1/users/{userId}/devices/{deviceId}/connect).
email-verification-required
The email-verification capability is present
Resolve via PUT /v1/users/{userId}/devices/{deviceId}/email-verification.
Subscription / Automation
Smart mode
Intervention
When you see it
Resolution
subscription-upgrade-required
Your plan is free or expired. On a starter plan, only if another device already has smart mode enabled.
Not resolvable via the Connect API. Direct the user to upgrade their clever-PV plan in the customer portal; the intervention clears automatically once the new plan is active.
Scheduling
Intervention
When you see it
Resolution
subscription-upgrade-required
Your plan does not include the Schedule feature.
Not resolvable via the Connect API. Direct the user to upgrade to a plan that includes scheduling; the intervention clears automatically once the new plan is active.
Battery automation
Intervention
When you see it
Resolution
solar-forecast-setup-required
Solar forecast is not enabled for the home.
Resolve by enabling Solar Forecast for the home.
battery-capacity-required
Battery capacity is missing on a device with an attached battery (the intervention is reported on the electric meter the battery is attached to).
Resolve by writing the battery-capacity capability on that device: PUT /v1/users/{userId}/devices/{deviceId}/battery-capacity with {"batteryCapacity": <value>} (nominal capacity in Wh).
battery-software-update-required
Vendor reports outdated battery software.
Resolve by updating the battery firmware in the vendor app/portal.
wrong-operating-mode
Battery is in a mode that blocks smart control.
Resolve by switching the battery to an allowed/automatic operating mode in the vendor app.
email-verification-required
Vendor email consent is missing (e.g., Fronius registration not verified).
Resolve by verifying the email/consent in the vendor portal; it clears after verification.
