Error Codes

Copy page

TL;DR

• Errors are returned as application/problem+json with type, title, status, detail, traceId, errorCode, and optionally issues[] and extensions
• Branch on errorCode — it is the stable identifier. detail is human-readable text and may change; the HTTP status alone is often ambiguous (e.g. 409 has more than ten causes)
• Keep the traceId of every failed request: support can find the request with it
• 401 for a missing or invalid API token and 429 (rate limit) come without a body
• 502 vendorCommunicationError is a temporary vendor-side failure — retry with increasing delays. 400/409/412/422 need a different request or a user action — retrying the same request does not help

Response shape

All errors raised by the Connect API use the same RFC 7807 problem-details shape (ConnectApiProblemDetails in the OpenAPI spec):

Code
{
  "type": "validationFailed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "One or more validation errors occurred. Please check the issues for details.",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "errorCode": "validationError",
  "issues": [
    { "field": "<field>", "message": "<rule that was violated>", "code": "<validator code>" }
  ]
}

Field	Description
type	Problem category (camelCase string), e.g. validationFailed, accessDenied, conflict, vendorCommunicationError. Several error codes share one type.
title	Short summary of the problem.
status	HTTP status code, same as the response status.
detail	Explanation of this occurrence. For display and logs only — do not parse it.
traceId	Identifier of the request. Include it when you contact support.
errorCode	Stable, partner-facing error code (camelCase string). Listed below.
issues	Only for request validation errors: one entry per violated rule with field, message and validator code.
extensions	Optional additional values for specific errors, e.g. vendorErrorCode (the vendor's own error code) or vendorId. Tolerate unknown keys.

New error codes can be added within /v1/ (see API Versioning). Treat an unknown errorCode by its HTTP status: 4xx means the request cannot succeed as sent, 5xx means a server or vendor-side failure.

Request body errors (no errorCode)

If the request body of a capability PUT cannot be read at all — the capability name in the path is unknown, the body is empty, it contains unknown fields or a wrapper such as { "data": { ... } }, or a value has the wrong type or enum value — the request fails before it reaches the API logic. The response is a standard ASP.NET validation problem without errorCode:

Code
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": { "data": ["Unknown capability: on-of"] },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Treat a 400 without errorCode as a malformed request; the messages in errors name the problem.

Responses without a body

Status	When
401	The bearer token is missing, expired or invalid (rejected before the request reaches the API). Fetch a new token, see Authentication.
429	The rate limit was exceeded. Wait and retry.
404 / 405	Unknown route, or a method the route does not support — e.g. GET .../devices/{deviceId}/{capability} returns 405 (capabilities are read via the device GET).

How to react

Situation	Typical codes	What to do
Request is wrong	validationError, invalidTimezone, invalidSchedule*, tariff*	Fix the request. For validationError, read issues[]. Do not retry unchanged.
A precondition is missing	interventionFound, paymentRequired, emailConsentRequired, teslaSdkRequired, chargingLocationNotVerified, homeLocationRequired	Read the device's interventions[] or the named prerequisite, let the user resolve it, then retry. See Interventions.
State conflict	duplicateDevice, pendingOcppWallboxExists, *ConnectionHasDevices, carLinkedToWallbox, measurementPurposeAlreadySet	Re-read the current state (connections, devices, capabilities) and adapt the next request.
Vendor login or permission	invalidCredentials, authenticationFailed (403), vendorPermissionDenied, vendorAuthorizationDenied, vendorAuthorizationFailed	The user must log in again or grant access at the vendor. A new vendor authorization is needed; resending the same request cannot succeed.
Vendor temporarily unavailable	vendorCommunicationError	Retry later with increasing delays (e.g. 30 s, 2 min, 10 min). The user does not need to change anything.
Access not configured	writeAccessNotEnabled, connectApiNotEnabledForApp	A configuration on the clever-PV side. Contact support.
Unexpected error	internalError with 500	Retry once later. If it persists, contact support with the traceId, the endpoint and the time.

Error code reference

The tables list every errorCode the Connect API returns, with the HTTP status it comes with.

Request and validation

errorCode	Status	Meaning	What to do
validationError	400	The request failed validation. issues[] lists field, message and rule where available; some checks only fill detail and leave issues empty. One issues[].code value is not a field rule: ACCESS_DENIED — the device does not belong to the user.	Fix the request. Validate against the capability's options before sending, see Capability options.
invalidTimezone	400	The X-Connect-TimeZone header is not a valid IANA time zone identifier.	Send an IANA id such as Europe/Berlin, or omit the header. See Home timezone.
operationFailed	400	A business rule prevented the operation and no more specific code applies.	Read detail; adapt the request.

Authentication and access

errorCode	Status	Meaning	What to do
authenticationFailed	401	The API token is valid, but no caller identity or app could be resolved from it.	Check that you use a token issued for your Connect API client. Contact support if it persists.
authenticationFailed	403	The vendor connection is invalid or has expired, or the vendor rejected clever-PV's access (vendor 401/403). Not related to your API token.	Let the user re-authenticate with the vendor via the connect capability (the device usually shows authentication-required).
accessDenied	403	Access to the resource is not allowed, e.g. an endpoint that is not available for end-user tokens.	Use a token with the required access.
writeAccessNotEnabled	403	Your partner account has read-only Connect API access. See Read and write access.	Contact clever-PV to enable write access.
connectApiNotEnabledForApp	403	The Connect API is not enabled for your partner or for the app whose customers you address.	Contact clever-PV.
routeUserMismatch	403	End-user token only: the {userId} in the path is not the user of the token.	Use the token user's own id.
userDeletionNotAvailable	403	Users of this app are managed in the whitelabel app and cannot be deleted through the API. See Deleting a User.	Delete the customer in the app.
paymentRequired	402	The home's subscription does not include the requested feature. The capability usually carries subscription-upgrade-required. Some capabilities used to return 400 instead, see Validation limits.	Upgrade the subscription, or hide the feature.

Users, homes and resources

errorCode	Status	Meaning	What to do
clientExternalUserNotFound	404	The {userId} does not resolve to a user you may access (unknown, not assigned to you, or not shared with you — the response does not say which).	Check the id. For whitelabel apps see Which userId to use.
missingHome	404	The user has no home, or the addressed home does not exist.	Check the user id.
deviceNotFound	404	The device does not exist.	Re-read GET /devices.
vendorNotFound	404	The vendor does not exist or is not available for your integration.	Re-read GET /vendors.
notFound	404	A requested resource does not exist and no more specific code applies.	Check ids in the path.
conflict	409	The request conflicts with the current state and no more specific code applies.	Re-read the resource and adapt the request.

Onboarding and connections

errorCode	Status	Meaning	What to do
unsupportedOnboardingFlow	400	The type in the create-connection body is not a valid onboarding flow.	Use the flow from connection options.
vendorFlowNotSupported	422	The vendor does not support the requested onboarding flow.	Use the vendor's flow.
vendorOnboardingFlowMissing	500	The vendor has no onboarding flow configured on the clever-PV side. extensions.vendorId names the vendor.	Contact support with the traceId.
invalidCredentials	401	The vendor rejected the submitted credentials (vendor account, not your API token).	Let the user check the credentials and repeat the flow. See verification errors.
vendorPermissionDenied	403	The vendor account is logged in but has no permission to bind or access this device. extensions.vendorErrorCode carries the vendor's code.	The user must grant the binding in the vendor's app or portal.
vendorAuthorizationDenied	400	The user cancelled or refused the authorization at the vendor. No connection was created.	Offer a new vendor authorization. See Vendor authorization errors.
vendorAuthorizationFailed	400	The vendor returned an OAuth error instead of an authorization code. No connection was created.	Start a new vendor authorization.
pendingOcppWallboxExists	409	The user already has an open OCPP connection. Only one is allowed per user.	Reuse it, or delete it first. See OCPP Wallbox Onboarding.
ocppConnectionNotFound	404	The OCPP connection does not exist.	Re-read the user's connections.
connectionNotFound	404	The connection does not exist for this user and vendor.	Re-read GET /vendors/connections.
deleteConnectionNotPossible	400	The connection cannot be deleted: not found, or deletion is not supported for its flow.	See Delete Connection.
ocppConnectionHasDevices / formConnectionHasDevices / pushConnectionHasDevices	409	The connection still has devices.	Delete the devices first, then the connection.
emailConsentRequired	412	The user still has to confirm an e-mail for the vendor.	Complete the email-verification step.

Devices and capabilities

errorCode	Status	Meaning	What to do
duplicateDevice	409	A device with this externalId already exists — in this home or in another one.	See What available: false means. This includes devices connected in the clever-PV app or in another partner's app. A device bound to another account must be released there.
deviceTypeNotSupported	404	The device model is not supported.	Pick a supported model from the catalog.
deviceCreationFailed	400	The create-device request is invalid.	Read detail and fix the request.
capabilityNotSupported	422	The device does not have this capability, or the operation is not supported for it.	Only write capabilities that appear in the device's capabilities[].
interventionFound	422	An active intervention blocks the capability.	Read interventions[] on the device and resolve it. See Interventions.
measurementPurposeAlreadySet	409	The measurement purpose was already set and cannot be changed.	Keep the device's purpose, or re-onboard it.
carLinkedToWallbox	409	The car is linked to a wallbox controlled by clever-PV; charging control lives on the wallbox.	Write boost, on-off or target-charging on the wallbox, or unlink the car. See target-charging details.
wallboxAlreadyLinkedToCar	409	The wallbox is already linked to another car.	Unlink the other car first.
wallboxRequiredForLink	409	The home has no wallbox the car could be linked to.	Onboard a wallbox first.
teslaSdkRequired	412	The clever-PV virtual key is not installed on the Tesla.	Run the install-certificate flow.
chargingLocationNotVerified	412	VW CCO: no charging location is set for the clever-PV charging contract in the vehicle.	See add-charging-location.
internalError	409	Deleting a device: the vendor-side reset failed and the device was not deleted. extensions.vendorErrorCode is ConnectionExpired, DeviceUnreachable or ResetFailed.	See Delete Device; use force=true only after the user confirmed.

Vendor communication

errorCode	Status	Meaning	What to do
vendorCommunicationError	502	The vendor's system did not answer, timed out, answered with a server error or an unusable response, or throttled the request (a vendor 429 is reported as this 502). The request itself was valid.	Retry later with increasing delays. Do not ask the user to change credentials because of this error.
internalError	vendor status	The vendor answered with another unexpected HTTP status; the status is passed through.	Treat like vendorCommunicationError if it is a 5xx; otherwise contact support with the traceId.

Schedules

errorCode	Status	Meaning	What to do
invalidScheduleExecutionTime	400	executionTime is not on the five-minute grid or outside 00:00:00–23:55:00.	See time-control details.
invalidSchedulePayload	400	Schedule fields are missing or inconsistent.	See Schedule validation errors.
scheduleOverlapping	409	Two schedules in the submitted list overlap.	Send a list without overlaps.

Electricity tariffs

errorCode	Status	Meaning
tariffBettingZoneRequired	400	A dynamic tariff needs a bidding zone.
tariffPriceRequired	400	A fixed tariff needs a price.
tariffInvalidDateRange	400	from must be before to.
tariffNotFound	404	The tariff does not exist.
flexFeesNotFound	404	No flexible grid fees were found.
tariffOverlapping	409	The tariff's period overlaps another tariff of the same kind.
tariffContractAttached	409	The tariff has an attached contract and cannot be modified.
tariffSavingsNotCreated	409	Initial savings for a device have not been created yet.
tariffTypeImmutable	422	The tariff type of an existing tariff cannot be changed.
tariffPriceTypeImmutable	422	The price type of an existing tariff cannot be changed.
tariffInPastNotAllowed	422	A tariff cannot be created or changed in the past.

See Electricity Tariffs for the request rules.

Home forecast

errorCode	Status	Meaning	What to do
homeLocationRequired	409	The home has no location.	Set the home location.
solarProducerRequired	409	The home has no producing device (inverter or PV meter).	Onboard a producing device.
solarForecastDisabled	409	The solar forecast is disabled for the home.	Enable it.
solarForecastNotAvailable	404	The forecast is enabled but not generated yet.	Retry after a few minutes.

Server errors

errorCode	Status	Meaning	What to do
internalError	500	An unexpected error on the clever-PV side. Some out-of-range capability values also end up here instead of a 400 — e.g. amperages, charge limits or an unsupported automatic phase mode, see Validation limits.	Check the values against the capability's options. Otherwise retry once later; if it persists, contact support with the traceId, the endpoint and the time.

The PartnerErrorCode enum in the OpenAPI spec contains further values from shared components of the platform (e.g. invalidSubscription, invalidCouponCode, rateLimitExceeded, chargingLimitReached). They are not part of the documented Connect API behavior; if one appears, handle it by its HTTP status and contact support with the traceId.

Contacting support

Open a ticket via Support and include:

• the traceId from the response,
• endpoint, HTTP method and time of the request (with time zone),
• status and errorCode,
• the affected userId and, if any, deviceId.

Do not send API tokens, client secrets or vendor passwords.