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

# Errors

> The HTTP status codes, the error object and the errors your integration must handle.

| Status | Meaning | `type` |
| :- | :- | :- |
| `2XX` | Success | |
| `4XX` | Your request is invalid | `invalid_request` |
| `429` | Too many requests | `rate_limit` |
| `5XX` | Flatpeak cannot process the request | `api_error` |

## Error object

Every endpoint returns errors in the same object.

```json theme={"system"}
{
  "object": "error",
  "live_mode": false,
  "type": "invalid_request",
  "code": "access_denied",
  "message": "You do not have access to this device",
  "context": "api.device_get",
  "time_created": "2026-07-08T14:15:22Z"
}
```

| Property | Description |
| :- | :- |
| `type` | `invalid_request`, `rate_limit` or `api_error` |
| `code` | Machine-readable, so branch on it. The table below lists the codes to handle, and each endpoint in the [API reference](/docs/fleet-api/reference.md) names its own in its description |
| `message` | Human-readable description |
| `context` | Optional. The service and method that raised the error, such as `api.device_get` |
| `live_mode` | `true` for a live secret key, `false` for a test key |
| `time_created` | RFC 3339 timestamp |

## Errors to handle

| Code | Status | Meaning | Do |
| :- | :- | :- | :- |
| `plan_not_allowed` | `422` | Plans are for managed tariffs. The device has no `ACTIVE` enrollment in one of your managed [programs](/docs/fleet-api/guides/programs.md) | Do not retry the plan unchanged. To commit other devices, create a [VPP event](/docs/fleet-api/guides/dispatch/vpp-events.md) |
| `plan_rate_limited` | `429` | More than 12 plans in one hour for one device | Wait `retry_after` seconds |
| `terms_required` | `422` | A `listed` program with `managed` `false` cannot go `LIVE` without a reward | Add at least one entry to `terms.rewards` |
| `signup_url_required` | `422` | A `listed` managed program cannot go `LIVE` without `enrollment.signup_url` | Add `enrollment.signup_url` |
| `signup_reference_invalid` | `422` | The `signup_reference` on a Connect session is unknown, already used, expired, or issued for another `oem_id` or `program_id` | Create the session without it. The customer picks the device in the OEM app |
| `enrollment_not_awaiting_approval` | `422` | [Approve](/docs/fleet-api/reference/vpp-enrollments/approve.md) was called on an enrollment that is not at step `AWAITING_APPROVAL` or `UNENROLLING` | Retrieve the enrollment and read `enrollment_step` |
| `enrollment_ended` | `422` | [Unenroll](/docs/fleet-api/reference/vpp-enrollments/unenroll.md) was called on an enrollment that is `ENDED` or `REJECTED` | Nothing. The enrollment is already over |
| `vpp_event_finished` | `422` | [Cancel](/docs/fleet-api/reference/vpp-events/cancel.md) was called on a `COMPLETE` or canceled VPP event | Nothing. The event is already over |
| `reference_id_exists` | `409` | A VPP event with that `reference_id` already exists | Treat the retry as done: the first request created the event |
| `export_scope_invalid` | `422` | An [export](/docs/fleet-api/reference/exports/create.md) names both `program_id` and `group_id`, or neither | Send exactly one of the two |
| `setting_not_supported` | `422` | A settings update names a field path that is not in the device's `supported` list | Read `supported` on the [settings](/docs/fleet-api/reference/devices/retrieve-settings.md) and send only those paths |
| `account_disabled` | `422` | Your account is disabled, for example out of subscription. Every endpoint returns it | Restore billing in [Console](https://console.flatpeak.com) > **Settings** > **Billing**, or contact [support](https://console.flatpeak.com/support) |
| `too_many_requests` | `429` | You exceeded 400 requests per second on one endpoint | Back off exponentially and batch requests. A retry in a tight loop extends the throttling |
| `cursor_invalid`, `pagination_params_invalid` | `400` | The cursor or `limit` is invalid | See [pagination](/docs/fleet-api/guides/platform/pagination.md#errors) |

[Submit a dispatch plan](/docs/fleet-api/reference/plans/submit.md) returns the three plan errors. An OEM receives at most one instruction every five minutes for one device.


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