Authentication and access
| Code | Status | Description |
|---|---|---|
UNAUTHORIZED | 401 | No API key was sent. |
INVALID_API_KEY | 401 | The API key is unrecognised or revoked. |
EXPIRED_TOKEN | 401 | The API key has expired. |
FORBIDDEN | 403 | Access to this resource is forbidden. |
INSUFFICIENT_PERMISSIONS | 403 | The API key lacks the required permission. |
LIVE_ACCESS_DISABLED | 403 | Your account isn’t enabled for live yet. |
CONSENT_REVOKED | 403 | The end user revoked access to this device. |
DEVICE_OVERAGE | 403 | Your account has exceeded its device limit. |
RATE_LIMIT_EXCEEDED | 429 | Your API key has exceeded its rate limit. |
Request validation
| Code | Status | Description |
|---|---|---|
VALIDATION_ERROR | 400 | A query parameter is out of bounds, or the body isn’t valid JSON. |
INVALID_REQUEST_BODY | 400 | The request body is invalid, for example an unknown key or a start with a UTC offset. |
EMPTY_SETTINGS | 400 | A settings update must include at least one setting. |
PAYLOAD_TOO_LARGE | 413 | The request body is too large. |
UNSUPPORTED_MEDIA_TYPE | 415 | Send Content-Type: application/json. |
METHOD_NOT_ALLOWED | 405 | The method isn’t allowed on this route, such as a POST to a solar inverter. |
Devices and actions
| Code | Status | Description |
|---|---|---|
NOT_FOUND | 404 | The resource doesn’t exist. |
DEVICE_TYPE_MISMATCH | 404 | The device exists but isn’t this device type. Check the route. |
ACTION_NOT_FOUND | 404 | The action doesn’t exist. |
ACTION_NOT_CANCELLABLE | 409 | Only scheduled actions can be cancelled. |
GONE | 410 | The resource is no longer available. |
Capabilities
| Code | Status | Description |
|---|---|---|
DEVICE_NOT_CAPABLE | 422 | The device doesn’t offer what you asked for: a command, parameter, unit, timing, onConflict strategy, setting, or charging-session history. Don’t retry. |
CAPABILITY_PAUSED | 503 | Amps has temporarily paused this capability. Retry with backoff. |
DEVICE_NOT_CAPABLE can carry details. Read each field by presence.
| Refused | details can include |
|---|---|
| Command | deviceCapabilities.supportedModes |
| Parameter | unsupportedParameters, deviceCapabilities.supportedParameters |
| Unit | parameter, providedUnit, supportedUnits |
| Timing | requestedExecution, supportedExecution |
onConflict strategy | requestedStrategy, supportedStrategies |
| Unknown setting | availableSettings |
| Read-only setting | setting |
Commands
| Code | Status | Description |
|---|---|---|
PARAMETER_OUT_OF_RANGE | 422 | A parameter is outside the device’s min/max, or off its step grid. |
UNSUPPORTED_PARAMETER_COMBINATION | 422 | Two parameters cap the same thing, such as power and current. Send one. |
Scheduling
| Code | Status | Description |
|---|---|---|
START_IN_PAST | 422 | start is in the past. |
START_OUT_OF_RANGE | 422 | start is more than 30 days ahead. |
START_INVALID_FORMAT | 422 | start isn’t a real date and time. |
START_NONEXISTENT_WALL_CLOCK | 422 | start falls in a daylight-saving gap. |
INVALID_TIME_WINDOW | 422 | end is in the past, more than 30 days ahead, not after start, or a window the device can’t hold. See details.reason. |
TIMEZONE_UNRESOLVED | 422 | The device’s timezone is unknown. |
INVALID_TIMEZONE | 422 | The device’s timezone is invalid. |
Conflicts
| Code | Status | Description |
|---|---|---|
CONFLICT | 409 | Another action is active on this device. |
CONFLICT_IN_EXECUTION | 409 | A conflicting action is already running and can’t be interrupted. |
SCHEDULER_ACTIVE | 409 | A schedule on the device must be cleared first. |
SCHEDULER_FULL | 409 | The device’s schedule is full. |
MODE_OVERRIDDEN | 409 | The device is in a state that overrides this command. |
VPP_LOCKED | 409 | Another control programme has locked the device. |
VEHICLE_NOT_CONNECTED | 409 | No vehicle is plugged in to the charger. |
Settings
| Code | Status | Description |
|---|---|---|
INVALID_SETTING_UNIT | 422 | The unit is invalid. |
INVALID_SETTING_VALUE | 422 | The value is the wrong type. |
SETTING_OUT_OF_RANGE | 422 | The value is outside the allowed range, or beyond a narrower limit the connected unit reports. |
UNSUPPORTED_SETTING_COMBINATION | 422 | Two settings in the request set the same thing. |
SETTINGS_STORE_UNAVAILABLE | 503 | Settings are temporarily unavailable. Retry. |
End-user account
These come from the manufacturer account the end user linked. Most are fixed by reconnecting through Link UI.| Code | Status | Description |
|---|---|---|
INVALID_CREDENTIALS | 401 | The manufacturer rejected the end user’s credentials. |
MFA_REQUIRED | 403 | The manufacturer requires multi-factor authentication. |
INVALID_MFA_CODE | 403 | The multi-factor code wasn’t accepted. |
ACCOUNT_LOCKED | 403 | The manufacturer account is locked. The end user must unlock it with the manufacturer. |
DEVICE_UNAUTHORIZED | 403 | The end user’s account can no longer control this device. |
UNSUPPORTED_CREDENTIAL_TYPE | 400 | The stored credential type isn’t supported for this device. |
UNSUPPORTED_AUTH_PATH | 400 | The authentication method isn’t supported. |
BIND_NOT_SUPPORTED | 400 | The manufacturer doesn’t support linking this device. |
CREDENTIAL_NOT_FOUND | 404 | No stored credential for this device. |
NO_DEVICES_FOUND | 404 | The linked account has no devices. |
Device and manufacturer
These often appear on a failed action’serrorCode rather than as an HTTP response.
| Code | Status | Description |
|---|---|---|
DEVICE_OFFLINE | 410 | The device is offline. Retry once it’s back. |
DEVICE_NOT_FOUND | 404 | The manufacturer can’t find the device. |
COMMAND_FAILED | 400 | The manufacturer couldn’t complete the command. |
COMMAND_NOT_APPLIED | 409 | Amps read the device back and the command hadn’t taken effect. |
INVALID_PARAMETERS | 400 | One or more parameters were invalid. |
INVALID_OEM_PARAMETERS | 400 | The manufacturer rejected one or more parameters. |
INVALID_OEM_RESPONSE | 502 | The manufacturer returned data Amps couldn’t use. details.fields names each reading. Don’t retry. |
STALE_ACTION | 410 | The action expired before it could run. Resubmit it. |
RATE_LIMITED | 429 | The manufacturer is rate limiting. Retry with backoff. |
NETWORK_ERROR | 502 | The manufacturer couldn’t be reached. Retry with backoff. |
SERVICE_UNAVAILABLE | 503 | The manufacturer is unavailable. Retry with backoff. |
TIMEOUT | 504 | The manufacturer didn’t respond in time. Retry with backoff. |
SIMULATED_FAILURE | 503 | A simulated failure in sandbox. |
Server
| Code | Status | Description |
|---|---|---|
INTERNAL_ERROR | 500 | Unexpected error. Retry once, then contact support. |
UNKNOWN_ERROR | 500 | Unclassified manufacturer response. Retry once, then contact support. |
DEFERRED_SCHEDULE_FAILED | 500 | A scheduled action couldn’t be set up. Resubmit it. |
UNROUTABLE_ACTION_TYPE | 500 | The command never reached the device. Contact support with the requestId. |
NOT_IMPLEMENTED | 501 | This endpoint isn’t available yet. |
BAD_GATEWAY | 502 | An upstream service returned an invalid response. |
GATEWAY_TIMEOUT | 504 | An upstream service didn’t respond in time. |