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
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | Invalid input. |
| 401 | unauthorized | Incorrect credential. |
| 404 | not_found, no_such_machine | Unknown route or machine. |
| 405 | method_not_allowed | Wrong method. |
| 409 | wrong_state, ambiguous | State conflict or duplicate name. |
| 500 | failed | Host 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.