Getting started

Use the ZYNOO API to order VPS hosting and manage servers from your own application. You can also manage existing VPSs without placing orders through the API.

Base URL

https://bill.zynoo.com/vps-api/index.php

Make your first request

Create an API credential under API Access in your reseller account.
Follow Authentication to sign a request.
Call GET /v1/vps to list your VPSs. Save each remote_service_id to use in later requests.

Set up authentication →Import your VPS catalog →

Requests and responses

Use HTTPS and send request bodies as JSON. Responses contain ok: true on success, or ok: false with an error object.

Every request except /v1/ping needs the authentication headers. Examples on the following pages show the URL and body; add those headers to your request. Response examples show selected fields. IDs, prices and addresses are illustrative.

Check the API

A public availability check. No API credential is required.

GET/v1/ping

Scope: None

cURL

curl 'https://bill.zynoo.com/vps-api/index.php/v1/ping'

Response · HTTP 200

Example response

{
  "ok": true,
  "api": "v1",
  "server_time": 1700000000
}

Your account

Get your balance, currency, reseller discount and API permissions.

GET/v1/account

Scope: account:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/account

Response · HTTP 200

Example response

{
  "ok": true,
  "account": {
    "currency": {
      "code": "USD"
    },
    "prepaid_credit": {
      "balance": 100
    },
    "tier": {
      "name": "Example tier",
      "discount_percent": 10
    },
    "permissions": {
      "new_orders": true,
      "lifecycle": true
    }
  }
}

Authentication

Your API Access ID identifies your account. Your secret signs each request; it is never sent to the API. Make calls from your backend and keep both values out of browser code.

Required headers

Header	What to send
`X-VR-Key`	Your API Access ID.
`X-VR-Timestamp`	Current Unix time in seconds. Keep your server clock accurate; the default tolerance is five minutes.
`X-VR-Nonce`	A fresh random string for each request: 12–120 letters, digits, or `._~-`.
`X-VR-Signature-Version`	`2`
`X-VR-Signature`	The hexadecimal HMAC-SHA256 signature described below.
`Content-Type`	`application/json` when sending a body.

Use X-Idempotency-Key for safe retries of orders, power actions and reinstalls. Save one unique key per logical action; reuse it only for that same action. Use 1–128 letters, digits, or ._:-.

Create the signature

Join these six values with a single LF newline (\n) between them, then calculate HMAC-SHA256 using your API secret:

Signature input

timestamp
nonce
HTTP_METHOD
/v1/request/path
SHA256(request_body)
idempotency_key

Use the uppercase method and decoded path, such as /v1/vps. Exclude the domain, /vps-api/index.php and query string. Hash the exact body bytes you send; for GET, hash an empty string. If there is no action key, leave the sixth value empty. Do not append another newline.

Complete PHP example: list your VPSs

Requires PHP 8.1+ with cURL. Set ZYNOO_API_KEY and ZYNOO_API_SECRET in your server environment, then run this example. It makes one read-only request.

PHP

$key = (string) getenv('ZYNOO_API_KEY');
$secret = (string) getenv('ZYNOO_API_SECRET');
if ($key === '' || $secret === '') {
    throw new RuntimeException('Set API credentials on your backend.');
}
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(18));
$path = '/v1/vps';
$canonical = implode("\n", [
    $timestamp, $nonce, 'GET', $path, hash('sha256', ''), ''
]);
$signature = hash_hmac('sha256', $canonical, $secret);

$ch = curl_init('https://bill.zynoo.com/vps-api/index.php' . $path . '?limit=100');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 45,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-VR-Key: ' . $key,
        'X-VR-Timestamp: ' . $timestamp,
        'X-VR-Nonce: ' . $nonce,
        'X-VR-Signature-Version: 2',
        'X-VR-Signature: ' . $signature,
    ],
]);
$raw = curl_exec($ch);
$httpStatus = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($raw === false) throw new RuntimeException('API connection failed.');
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ($httpStatus !== 200 || empty($result['ok'])) {
    throw new RuntimeException($result['error']['message'] ?? 'API request failed.');
}
foreach ($result['services'] as $vps) {
    echo $vps['remote_service_id'] . ': ' . $vps['status'] . PHP_EOL;
}

Permissions

Enable the scopes needed by your integration when creating the credential. Each endpoint below lists its scope. If you set an IP allowlist, use the public IP of the server making your API calls.

Plans & orders

Choose a plan, read its available options, then submit an order. Use the values returned by the API for operating systems and other options.

List plans

Get every active reseller catalog plan in your account currency, with prices and provisioning choices. This endpoint is not paginated.

GET/v1/plans

Scope: catalog:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/plans

Response · HTTP 200

Example response

{
  "ok": true,
  "currency": "USD",
  "plans": [
    {
      "pid": 10,
      "name": "Example VPS",
      "prices": {
        "monthly": {
          "recurring": 12,
          "setup": 0
        }
      }
    }
  ]
}

Plan import examples

These read-only examples fetch all plans and print JSON for your billing adapter. Set ZYNOO_API_KEY and ZYNOO_API_SECRET on your backend; the credential needs catalog:read.

Create or update your local products using supplier_pid as the external key.
Keep each offered billing cycle and build option fields from provisioning.
Send that PID and the selected option values when ordering. Refresh one plan with GET /v1/plans/{pid}.

PHP · import-plans.php

Download

<?php
// PHP 8.1+ with cURL. Run on your backend with catalog:read permission.
$key = (string) getenv('ZYNOO_API_KEY');
$secret = (string) getenv('ZYNOO_API_SECRET');
if ($key === '' || $secret === '') {
    throw new RuntimeException('Set ZYNOO_API_KEY and ZYNOO_API_SECRET.');
}

$path = '/v1/plans';
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(18));
$canonical = implode("\n", [
    $timestamp, $nonce, 'GET', $path, hash('sha256', ''), ''
]);
$signature = hash_hmac('sha256', $canonical, $secret);

$ch = curl_init('https://bill.zynoo.com/vps-api/index.php' . $path);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 45,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-VR-Key: ' . $key,
        'X-VR-Timestamp: ' . $timestamp,
        'X-VR-Nonce: ' . $nonce,
        'X-VR-Signature-Version: 2',
        'X-VR-Signature: ' . $signature,
    ],
]);
$raw = curl_exec($ch);
$httpStatus = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
$transportError = curl_error($ch);
curl_close($ch);
if ($raw === false) throw new RuntimeException($transportError);
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ($httpStatus !== 200 || empty($result['ok'])) {
    throw new RuntimeException('HTTP ' . $httpStatus . ': '
        . ($result['error']['code'] ?? 'request_failed'));
}

// Upsert local billing products by supplier_pid; keep every offered cycle.
$products = [];
foreach ($result['plans'] as $plan) {
    $products[] = [
        'supplier_pid' => (int) $plan['pid'],
        'name' => $plan['name'],
        'group' => $plan['group'],
        'prices' => $plan['prices'],
        'provisioning' => $plan['provisioning'],
    ];
}
echo json_encode(['currency' => $result['currency'], 'products' => $products],
    JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR) . PHP_EOL;

Python · import-plans.py

Download

# Python 3, standard library only. Requires catalog:read permission.
import hashlib
import hmac
import json
import os
import secrets
import time
from urllib.error import HTTPError
from urllib.request import Request, urlopen

key = os.environ["ZYNOO_API_KEY"]
secret = os.environ["ZYNOO_API_SECRET"]
path = "/v1/plans"
timestamp = str(int(time.time()))
nonce = secrets.token_hex(18)
canonical = "\n".join([
    timestamp, nonce, "GET", path, hashlib.sha256(b"").hexdigest(), ""
])
signature = hmac.new(
    secret.encode("utf-8"), canonical.encode("utf-8"), hashlib.sha256
).hexdigest()

request = Request(
    "https://bill.zynoo.com/vps-api/index.php" + path,
    headers={
        "Accept": "application/json",
        "X-VR-Key": key,
        "X-VR-Timestamp": timestamp,
        "X-VR-Nonce": nonce,
        "X-VR-Signature-Version": "2",
        "X-VR-Signature": signature,
    },
    method="GET",
)
try:
    with urlopen(request, timeout=45) as response:
        result = json.load(response)
except HTTPError as error:
    failure = json.loads(error.read())
    raise RuntimeError(f"HTTP {error.code}: {failure['error']['code']}") from error
if not result.get("ok"):
    raise RuntimeError(result.get("error", {}).get("code", "request_failed"))

# Upsert local billing products by supplier_pid; keep every offered cycle.
products = [{
    "supplier_pid": int(plan["pid"]),
    "name": plan["name"],
    "group": plan["group"],
    "prices": plan["prices"],
    "provisioning": plan["provisioning"],
} for plan in result["plans"]]
print(json.dumps({"currency": result["currency"], "products": products},
                 indent=2, ensure_ascii=False))

The scripts output product data; your adapter writes it to your billing system. Use the returned currency and prices, and keep your retail markup separate.

Plan options

Replace {pid} with a plan’s pid. The provisioning object lists required fields and valid choices.

GET/v1/plans/{pid}

Scope: catalog:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/plans/10

Response · HTTP 200

Example response

{
  "ok": true,
  "currency": "USD",
  "plan": {
    "pid": 10,
    "name": "Example VPS",
    "prices": {
      "monthly": {
        "recurring": 12,
        "setup": 0
      }
    },
    "provisioning": {
      "operating_system": {
        "required": true,
        "choices": [
          {
            "value": "ubuntu-example",
            "label": "Example Ubuntu image"
          }
        ]
      },
      "configurable_options": [
        {
          "name": "number_of_ips",
          "required": true,
          "choices": [
            {
              "value": "1",
              "label": "1 IP"
            },
            {
              "value": "2",
              "label": "2 IPs"
            }
          ]
        }
      ],
      "custom_fields": []
    }
  }
}

Use prices to find available billing cycles. Check the required flags for hostname, root_password, operating_system, configurable_options and custom_fields. Base recurring prices already include your discount; option recurring prices are before that discount. Each price is for its full billing cycle. Setup fees are not tier-discounted; the invoice includes the final total and applicable taxes.

Order a VPS

Create an order using a plan ID and its options. Your account must have ordering enabled. Payment or available credit determines when provisioning can proceed.

POST/v1/orders

Scope: services:create

Body field	Value
`client_service_key`	Required. Your unique, permanent ID for this VPS, e.g. `store:42`. Use 1–128 letters, digits or `._:-`.
`pid`	Required. Plan ID.
`billing_cycle`	An offered billing cycle; defaults to `monthly`.
`hostname`	If required: a DNS hostname, up to 255 characters.
`root_password`	If required: 8–128 UTF-8 bytes, without control characters.
`operating_system`	The selected OS `value` from the plan.
`configurable_options / custom_fields`	Objects containing the required field names and their values.

Example request

POST https://bill.zynoo.com/vps-api/index.php/v1/orders
Content-Type: application/json
X-Idempotency-Key: order-42

{
  "client_service_key": "store:42",
  "pid": 10,
  "billing_cycle": "monthly",
  "hostname": "vps.example.net",
  "root_password": "REPLACE_WITH_PRIVATE_PASSWORD",
  "operating_system": "ubuntu-example",
  "configurable_options": {
    "number_of_ips": "2"
  }
}

In this example, number_of_ips: "2" requests two IP addresses. Replace the example field names and values with those returned for your plan.

Response · HTTP 201

Example response

{
  "ok": true,
  "service": {
    "remote_service_id": "ZV-ABC-0101",
    "client_service_key": "store:42",
    "status": "Pending",
    "hostname": "vps.example.net",
    "dedicated_ip": "",
    "assigned_ips": [],
    "reseller_hold": false,
    "supplier_hold": false,
    "provisioning_state": "awaiting_payment"
  }
}

A new order returns 201. Save service.remote_service_id and use Get a VPS to check its status. Pending means it is not ready yet; Active means the service is active.

If the request times out, look up the VPS using your original client_service_key. If you retry, keep the same client key, action key and body. A repeated request returns the existing result with 200; changing its body returns 409.

Your VPSs

Use the remote_service_id from your VPS list in place of {reference}. For example: ZV-ABC-0101. Your original client_service_key is also accepted. URL-encode the reference when building the path.

List your VPSs

Returns the VPS records belonging to your account. The list includes every service status unless you add a filter.

GET/v1/vps

Scope: services:read

Query parameter	Value
`status`	Optional: `active`, `pending`, `suspended`, `terminated` or `error`.
`limit`	Records per page: 1–250. Default: 100.
`cursor`	The `next_cursor` returned by the previous page.

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/vps?status=active&limit=100

Response · HTTP 200

Example response

{
  "ok": true,
  "services": [
    {
      "remote_service_id": "ZV-ABC-0101",
      "client_service_key": "store:42",
      "status": "Active",
      "hostname": "vps.example.net",
      "dedicated_ip": "198.51.100.10",
      "assigned_ips": [],
      "reseller_hold": false,
      "supplier_hold": false
    }
  ],
  "pagination": {
    "limit": 100,
    "has_more": false,
    "next_cursor": null
  }
}

When has_more is true, request the next page using cursor and the same status filter. Service status and power state are separate: an Active VPS can be powered off.

Get a VPS

Get the hostname, IP addresses, service status and latest reinstall operation for one VPS.

GET/v1/vps/{reference}

Scope: services:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101

Response · HTTP 200

Example response

{
  "ok": true,
  "service": {
    "remote_service_id": "ZV-ABC-0101",
    "client_service_key": "store:42",
    "status": "Active",
    "hostname": "vps.example.net",
    "dedicated_ip": "198.51.100.10",
    "assigned_ips": [],
    "reseller_hold": false,
    "supplier_hold": false
  }
}

Get multiple VPSs

Read up to 100 VPS records in one request. Results are keyed by the reference you send. Missing or unowned references appear in errors with service_not_found.

POST/v1/vps/query

Scope: services:read

Example request

POST https://bill.zynoo.com/vps-api/index.php/v1/vps/query
Content-Type: application/json

{
  "references": [
    "ZV-ABC-0101"
  ]
}

Response · HTTP 200

Example response

{
  "ok": true,
  "services": {
    "ZV-ABC-0101": {
      "remote_service_id": "ZV-ABC-0101",
      "client_service_key": "store:42",
      "status": "Active",
      "hostname": "vps.example.net",
      "dedicated_ip": "198.51.100.10",
      "assigned_ips": [],
      "reseller_hold": false,
      "supplier_hold": false
    }
  },
  "errors": {}
}

Resource usage

Read CPU, memory, disk, bandwidth and power state. The VPS must be Active and have no suspension holds.

GET/v1/vps/{reference}/metrics

Scope: services:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/metrics

Response · HTTP 200

Example response

{
  "ok": true,
  "metrics": {
    "available": true,
    "power_state": "online",
    "cpu_percent": 2.4,
    "memory_used_mb": 512,
    "memory_total_mb": 2048,
    "disk_used_gb": 4.2,
    "disk_total_gb": 40,
    "cache_seconds": 1800,
    "collected_at": "2026-09-21 10:00:00",
    "status_collected_at": "2026-09-21 10:05:00",
    "server_timezone": "UTC"
  }
}

Resource readings normally refresh every 30 minutes. Use collected_at and cache_seconds to show their age. A new VPS may need a minute or two before readings become available. Display unavailable or null values as unavailable, not zero.

Refresh power state

Get a fresh online/offline reading. This does not force new CPU, memory or disk readings.

GET/v1/vps/{reference}/metrics/refresh

Scope: services:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/metrics/refresh

The response uses the same metrics object. power_state is online, offline, suspended or unknown; status_collected_at is its timestamp. Timestamps use server_timezone.

Older service references

Get a ZYNOO reference

Convert an older reference to the current ZYNOO format. Send {}. Returns service.remote_service_id; an existing ZYNOO reference is returned unchanged. Requires services:read and services:reference:write.

POST/v1/vps/{reference}/reference

Scope: services:reference:write

Example request

POST https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/reference
Content-Type: application/json

{}

Power & access

Use these requests to control a VPS or change its password. Your credential needs the listed scope, and your account must allow VPS management. Check customer ownership in your application before sending a command.

Power controls

The VPS must be Active, without a suspension hold or an unfinished reinstall. Send {} and an X-Idempotency-Key for the action. See cooldown and retry rules.

Endpoint · scope: power:write	Action
`POST /v1/vps/{reference}/start`	Start the VPS.
`POST /v1/vps/{reference}/stop`	Shut down the VPS gracefully.
`POST /v1/vps/{reference}/reboot`	Restart the VPS.
`POST /v1/vps/{reference}/poweroff`	Force the VPS off. Unsaved data may be lost.

Example request

POST https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/reboot
Content-Type: application/json
X-Idempotency-Key: reboot-42-1

{}

Response · HTTP 200

Example response

{
  "ok": true,
  "service": {
    "remote_service_id": "ZV-ABC-0101",
    "client_service_key": "store:42",
    "status": "Active",
    "hostname": "vps.example.net",
    "dedicated_ip": "198.51.100.10",
    "assigned_ips": [],
    "reseller_hold": false,
    "supplier_hold": false
  }
}

A successful response acknowledges the command. Call Refresh power state to check the result.

Change the root password

Set a new password for an Active VPS without holds or an unfinished reinstall. Use 8–128 UTF-8 bytes without control characters.

POST/v1/vps/{reference}/password

Scope: password:write

Example request

POST https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/password
Content-Type: application/json

{
  "password": "REPLACE_WITH_PRIVATE_PASSWORD"
}

Returns 200 with ok: true and a service object. The password is not returned.

Suspend or terminate a VPS

Scope: lifecycle:write. Send {} to each endpoint. These actions return 200 with ok: true and the updated service.

Endpoint	Action
`POST /v1/vps/{reference}/suspend`	Suspend the VPS.
`POST /v1/vps/{reference}/unsuspend`	Remove your suspension. A ZYNOO hold must be resolved separately.
`POST /v1/vps/{reference}/terminate`	Permanently delete the VPS and its data. Confirm with the customer first.

OS reinstall

Reinstalling a VPS replaces its operating system and deletes its existing data. Ask the customer to confirm before continuing. The service must be Active, without holds or an unfinished reinstall, and reinstall must be enabled for your account.

1. Choose an operating system

Get the operating systems available for this VPS. Use the returned value in your reinstall request; it may differ from the value used when ordering. Your account must allow VPS management.

GET/v1/vps/{reference}/reinstall-options

Scope: services:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/reinstall-options

Response · HTTP 200

Example response

{
  "ok": true,
  "options": [
    {
      "value": "1001",
      "label": "Example Ubuntu image",
      "distro": "ubuntu"
    }
  ],
  "collected_at": "2026-09-21 10:00:00"
}

2. Reinstall the VPS

Send the selected OS value, a new password and the VPS’s current hostname. All three fields are required. Allow at least 150 seconds for this request.

POST/v1/vps/{reference}/reinstall

Scope: reinstall:write

Example request

POST https://bill.zynoo.com/vps-api/index.php/v1/vps/ZV-ABC-0101/reinstall
Content-Type: application/json
X-Idempotency-Key: reinstall-42-1

{
  "operating_system": "1001",
  "password": "REPLACE_WITH_PRIVATE_PASSWORD",
  "confirmation_hostname": "vps.example.net"
}

The password must contain 8–128 UTF-8 bytes without control characters. confirmation_hostname must match the current hostname after trimming whitespace. Save your action key with this request.

Response · HTTP 202

Example response

{
  "ok": true,
  "service": {
    "remote_service_id": "ZV-ABC-0101",
    "latest_operation": {
      "id": "op_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
      "type": "reinstall",
      "state": "accepted",
      "requires_review": false,
      "message": "Reinstall request accepted; waiting for completion."
    }
  }
}

202 means the request was processed, not that installation is complete. Check service.latest_operation.state before showing success.

3. Check progress

Use the operation ID from service.latest_operation.id. Reinstall starts immediately; completion reporting can take a few minutes.

GET/v1/operations/{operation_id}

Scope: services:read

Example request

GET https://bill.zynoo.com/vps-api/index.php/v1/operations/op_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1

Response · HTTP 200

Example response

{
  "ok": true,
  "operation": {
    "id": "op_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
    "type": "reinstall",
    "state": "succeeded",
    "requires_review": false,
    "message": "Reinstall completed."
  }
}

State	Meaning
`running / accepted`	Still in progress.
`succeeded`	Installation completed.
`failed`	The request failed; read the message.
`unknown`	The outcome needs review. Contact support before retrying.

Errors & limits

When a request fails, check the HTTP status and the error.code field. Include request_id when contacting support.

Example error

{
  "ok": false,
  "error": {
    "code": "service_not_found",
    "message": "Service not found.",
    "request_id": "example-request-id"
  }
}

HTTP status codes

Status	What to do
400 / 413 / 415	Check JSON formatting, the 64 KiB body limit and Content-Type.
401	Check the access ID, signature and server clock.
403	Check credential scopes, account permissions and allowed source IPs.
404	Check the endpoint and VPS reference.
409	Read `error.code`: the VPS state, an action key, an existing operation or a reused nonce may conflict.
422	Correct the fields named in the error.
426	Use HTTPS.
429	Wait for Retry-After before sending another request.
5xx	An API or upstream error occurred. Keep the request ID and check the outcome before repeating a write.

Rate limits

All credentials for one reseller share 120 requests per minute. Each credential also has a configured limit, which may be lower. X-RateLimit-Limit describes the shared allowance; X-RateLimit-Scope: reseller identifies its scope. Use X-RateLimit-Remaining and Retry-After to pace requests.

For 429 rate_limit_exceeded, wait for Retry-After seconds. Use POST /v1/vps/query for up to 100 service records at once, and reuse cached metrics.

Cooldowns & retries

A timeout does not establish whether a write completed. Check the VPS or operation first. For a retry, retain the action key and payload, but generate a new timestamp, nonce and signature.

Condition	Response and next step
Power cooldown	120 seconds per VPS, shared across start, stop, reboot and poweroff and all credentials. `429 power_action_cooldown` includes `Retry-After` and `error.details.retry_after_seconds`. Wait before submitting another power command.
Operation in progress	`409 power_action_in_progress` or `service_operation_in_progress`: check status and wait; use `Retry-After` when present. Processing can outlast the power cooldown.
Reinstall cooldown	Five minutes between new reinstall requests. `409 reinstall_cooldown` does not include `Retry-After`; wait until five minutes after the last submission.
Unresolved reinstall	`409 operation_unresolved`: poll the existing operation. `running` or `accepted` means wait; `unknown` requires supplier review. An expired cooldown does not unblock an unresolved reinstall.

Example: power cooldown response

HTTP response

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 90

{
  "ok": false,
  "error": {
    "code": "power_action_cooldown",
    "message": "A power command was recently submitted. Wait before submitting another power command.",
    "details": {
      "retry_after_seconds": 90,
      "cooldown_seconds": 120
    },
    "request_id": "example-request-id"
  }
}

Use the returned wait time for your interface countdown. Read-only status checks remain available, subject to the API request limit.

Retry behavior by action

Action	Reuse the original action key
Order	Keep `client_service_key` and the same order payload. A replay returns the existing service with `200`, rather than creating another order.
Power command	The same key, VPS and action returns the previous successful result without sending the command again. For `409 power_action_outcome_unknown`, check the VPS or contact support; do not generate a new key to force a resend.
Reinstall	The same key and payload returns the stored operation with `202`. Read its state; `202` is not confirmation that the reinstall succeeded.
Password / lifecycle	These actions have no action-key duplicate protection. Check the service after a timeout before deciding whether to repeat the request.

409 idempotency_conflict means the key belongs to a different request. 409 auth_replay_detected means the authentication nonce was reused; create fresh authentication headers.