Skip to main content

Statuses and lifecycle

Most changes in ZennoHosting are applied asynchronously. A successful write only means the server accepted the work — the VM, network, backup or port forwarding rule reaches its target state later. Read that state from a single field: status.

One field for state

VMs, networks and public IPs all expose a status field with five possible values. This is what you should show in a UI and what automation should branch on.

  • creating — the resource is being provisioned and is not ready yet.

  • active — the resource exists and is in a normal, ready-to-use state.

  • updating — a change is being applied: start, stop, reboot, resize or rebuild.

  • deleting — the resource is being deleted.

  • failed — the resource entered a state it cannot recover from on its own and needs the provider's team.

active does not mean the last operation succeeded

active is also reported after an operation failed but was handled normally. A start, stop, reboot or resize that can simply be retried leaves the VM active; a delete whose failure was handled leaves the resource intact and active too. So status cannot tell you how a specific operation ended — the operation record can. failed means something different: the resource is broken and will not recover by itself.

Two questions, two sources

Keep "what state is the resource in" separate from "how did my operation end". The first is answered by the resource's status, the second by the operation record.

  • Resource status — what to display and when it is safe to move on.

  • Operation status — the outcome: Queued, InProgress, Compensation, Succeeded or Failed.

  • Operation failureCode — why it failed: insufficientCapacity, timeout or internal.

  • VM bootStatus — power only: Running or Stopped. This field is not deprecated and stays useful when power, not lifecycle, is what you care about.

  1. 1

    Send the mutating request

    Creation, updates, restores, network attachment and forwarding rules all run asynchronously rather than as an instant state transition.

  2. 2

    Keep the identifiers from the response

    Store the returned commandId along with the resource identifiers you already know. On some endpoints commandId is an internal identifier you cannot query; on others it is a real, pollable operation id. Which one you got is stated in the endpoint's reference page.

  3. 3

    Poll the resource, not the write response

    Read the VM, network, backup or public IP through its own endpoint and look at status. A background reconciliation job refreshes state roughly every 10 seconds, so a short delay is expected rather than a sign of trouble.

  4. 4

    Read the operation when you need the reason

    List the project's operations and find yours by id. failureCode answers "why", while currentState is an optional diagnostic label for the current step — its set of values is not stable, so never branch on it.

Where this matters most

  • Creating a VM, and starting, stopping or rebooting it.
  • Creating a private network and attaching or detaching VMs.
  • Creating a backup and restoring from it.
  • Creating, updating and deleting port forwarding rules.

While an operation runs, the resource is locked: concurrent changes to the same resource fail with 409 Conflict until it completes.

Retained for compatibility

Responses still carry fields from the previous generation. They are kept only for backward compatibility — use the replacement in new code.

  • operation and operationStatus on a resource are the low-level pair that status is derived from. Read status instead.

  • lastError is gone from operations: the reason now comes from failureCode.

  • vmCount on a project is deprecated — use resourceCounts.vms.

Rule of thumb

Build automation around observable resource state, not around write acknowledgements. A 202 says the work started. status says where the resource is now. The operation record says how a specific attempt ended.

POST/projects/{projectId}/vms

Accept a command to provision a VM.

GET/projects/{projectId}/vms/{vmId}

Read a VM status and bootStatus after an async operation.

GET/projects/{projectId}/operations

List the project's operations and their outcome.

GET/projects/{projectId}/operations/{operationId}

Read the status and failureCode of one operation.

GET/projects/{projectId}/vms/state-counts

Count VMs by status without walking the list pages.