Errors

Envelope

All error responses (developer API) share this shape:

{
  "detail":     "human-readable message",
  "code":       "machine_readable_code",
  "request_id": "req_01HX…"
}

The request_id is also returned in the X-Request-Id response header. Quote it in support tickets; server logs are indexed by it.

Codes

HTTP	code	Meaning
400	validation_error	Body failed schema validation.
400	manifest_invalid	Firmware manifest didn't pass the schema.
400	over_artifact_limit	Plan's monthly artifact cap reached.
401	unauthenticated	No or unparseable token.
403	forbidden	Token valid but lacks scope for this resource.
404	not_found	Resource doesn't exist or isn't visible to your token.
409	conflict	E.g. trying to lower a deployment's percentage.
413	payload_too_large	Binary larger than plan/server cap.
422	invalid_state_transition	E.g. resuming a superseded deployment.
429	rate_limited	(When/if rate limiting is enabled.)
500	internal_error	Bug. The request_id will appear in the server log.

Device API

The device API uses hardware-safe responses for business outcomes. You only get 4xx/5xx from /check/ or /status/ for genuine misuse (401/403) or infrastructure failure (5xx).