Errors - Flatpeak

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.

{
  "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 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	Do not retry the plan unchanged. To commit other devices, create a VPP event
`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 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 was called on an enrollment that is `ENDED` or `REJECTED`	Nothing. The enrollment is already over
`vpp_event_finished`	`422`	Cancel 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 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 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 > Settings > Billing, or contact 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

Submit a dispatch plan returns the three plan errors. An OEM receives at most one instruction every five minutes for one device.