API reference

Handle failure without parsing prose

Branch on HTTP status and stable codes; display messages to operators.

Error shape

{
  "error": {
    "code": "wrong_state",
    "message": "Debian is not running."
  }
}

Status and codes

StatusCodeMeaning
400bad_requestInvalid input.
401unauthorizedIncorrect credential.
404not_found, no_such_machineUnknown route or machine.
405method_not_allowedWrong method.
409wrong_state, ambiguousState conflict or duplicate name.
500failedHost operation failed.

State conflicts

Refresh after wrong_state; do not retry blindly. Decide whether the current state already satisfies the intent.

Compatibility

Ignore unknown response fields and discover optional capabilities. The v1 contract is additive.

Legacy shortcuts

/get and /set accept query tokens, but URLs leak into histories and logs. New clients should use v1 and Authorization headers.