> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amps.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error codes

> Every error code the Amps API returns.

See [Error handling](/guides/error-handling) for the response shape and retry rules.

## 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. |

On an immediate response, `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` |

See [Capabilities](/guides/capabilities#when-a-device-cant-do-something).

## 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](/guides/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's `errorCode` 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.