Errors

Every error uses the same envelope. Branch on code; error is a human-readable message you can show or log.

{
  "success": false,
  "error": "The VPS is restarting. Try again when it has finished.",
  "code": "VPS_BUSY"
}

AccessCopy Anchor Link

Request shapeCopy Anchor Link

Not found and scopeCopy Anchor Link

Anything the key cannot reach answers 404, whether it does not exist, belongs to another account, or lies outside the key's project. The API never answers 403 for a resource, so ids cannot be probed.

Server stateCopy Anchor Link

VPS_BUSY applies to start, stop, restart, terminate, reinstall, reset password, upgrade, snapshots and firewall changes. Reads, renewals and auto-renew are never blocked.

Business rulesCopy Anchor Link

Common REQUEST_ERROR reasons:

• The account reached its server limit (terminated servers do not count).
• Unknown plan, or no image for the requested osType and osVersion.
• Invalid server name or root password (the message gives the rule: 12 to 30 characters, letters, numbers and ! @ # $ % ^ *).
• The server is in a status the action does not accept, for example Cannot start instance in 'running' status.
• Upgrade to a plan in another region or family, a plan that is not larger, or an upgrade with nothing left to pay.
• Snapshot limit reached, snapshots not available on the plan, or a snapshot that is not ready or not on this server.

Nothing is charged when a request fails with one of these.

Failed jobsCopy Anchor Link

A paid job that fails after the call returned is settled automatically, once:

In every case lastJobStatus is error and lastJobError says why.

Ports, SSH, metrics and upgrade optionsCopy Anchor Link

BackupsCopy Anchor Link

The backup routes add their own codes:

A path longer than 1024 characters on the file list answers 422 VALIDATION.

Server errorsCopy Anchor Link

Handling errorsCopy Anchor Link

async function vpsApi(path, { method = 'GET', body, key } = {}) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(`https://api.helipod.io/api${path}`, {
      method,
      headers: {
        Authorization: `Bearer ${key}`,
        ...(body ? { 'Content-Type': 'application/json' } : {}),
      },
      body: body ? JSON.stringify(body) : undefined,
    });
    const json = await res.json();
    if (json.success) return json.data;

    if (json.code === 'RATE_LIMITED') {
      const wait = Number(res.headers.get('retry-after') ?? 1);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (json.code === 'VPS_BUSY') {
      await new Promise((r) => setTimeout(r, 10_000));
      continue;
    }
    throw Object.assign(new Error(json.error), { code: json.code, status: res.status });
  }
  throw new Error('Gave up after 5 attempts');
}

The helper retries RATE_LIMITED and VPS_BUSY only. INTERNAL_ERROR is safe to retry for reads and power actions. Do not retry paid calls (POST /vps, renew, upgrade, backup activation) blindly: check the current state first.