# Paid Subservers reference **Page:** foundation/servers/paid-subservers/reference [Download Raw Markdown](./foundation/servers/paid-subservers/reference.md) --- # Paid Subservers reference Lookup tables for [paid subservers](/foundation/servers/paid-subservers/). Every plan and subscription call is in the [Servers API](/api/servers/#paid-subserver-subscriptions). ## Plan limits Every limit of a plan except snapshots applies to the whole subserver and is shared by all the computers on it. The plan's values are in the plan list, and in the `plan` of each subscription. | Limit | Plan field | What counts | |---|---|---| | CPU and RAM | `resources.cpu_cores`, `resources.ram_gb` | The plan's CPU cores and memory are a ceiling on a machine shared with other customers. They are not reserved hardware, and there is no swap | | Disk | `resources.disk_limit_gb` | One disk quota shared by every computer on the subserver | | Disk speed | `resources.disk_io_read_mib`, `resources.disk_io_write_mib` | Reads and writes are each limited to the plan's disk speed | | Network speed | `resources.network_limit_mbps` | The plan sets a speed, not a volume. There is no traffic quota (see [network fair use](/foundation/pricing/#network-fair-use)) | | Computers | `resources.max_computers` | Every computer on the subserver, stopped ones included. Failed, deleted, deleting and `host_reinstalled` computers do not count. At the limit, delete a computer or [upgrade](/foundation/servers/paid-subservers/#upgrade-a-paid-subserver) | | Snapshots | `resources.snapshots_per_computer` | Each computer can keep up to the plan's number of snapshots | | Aliases | `max_proxy_aliases` | The [proxy aliases](/foundation/proxy/aliases/) of every computer on the subserver, disabled and expired ones included. At the limit, delete an alias or upgrade | | Bot URLs | `max_bot_urls` | The [Bot URLs](/kit/agent/bot-urls/create/) attached to computers on the subserver, turned-off, frozen and suspended ones included. Detached and deleted Bot URLs do not count. At the limit, delete a Bot URL, move one to another server, or upgrade | | Storage shares | `max_storage_shares` | The storage shares on the subserver. At the limit, creating another is refused with `400 SERVER_STORAGE_SHARE_LIMIT`: delete a share that uses this server first, or upgrade | | Processes | none | At most 4096 tasks (processes and threads) across the whole subserver, the same ceiling as the free server. See [process limit](/foundation/servers/#the-free-tier) for what happens when you reach it | | Hoody AI | `ai_tier`, `resources.ai_multiplier` | `ai_tier` is `free`, `plus` or `pro`; some AI models may be limited to tiers. `ai_multiplier` is the plan's AI allowance as a multiple of the Free plan. Each free model's limits are set separately and need not rise by exactly that factor: see the [free usage reading](/foundation/hoody-ai/models/reference/#free-usage-reading) | Once your account has held a paid subserver of any plan, it can use up to 50 [realms](/foundation/hoody-api/realms/#realm-limits) and keeps that limit after the subserver ends. The limit applies to the whole account, not to the subserver. ## At a limit | Limit reached | What you get | What to do | |---|---|---| | Aliases | Creating another alias is refused with `422 Validation Error`, a message starting with "Alias limit reached", and `data.field` set to `proxy_alias_limit` (with `data.limit` and `data.current_count`). Nothing is created | Delete an alias on that subserver, or follow `data.upgrade` when the error carries it, as for the computer limit. See [Alias limit reached](/foundation/proxy/aliases/reference/#alias-limit-reached) | | Bot URLs | Creating another Bot URL, or moving one onto the subserver, is refused with `400 SERVER_BOT_URL_LIMIT`, and `data` carries `max` and `used`. Nothing changes | Delete a Bot URL on that subserver, move one to another server, or upgrade to a plan with a higher limit. See [How many URLs a server allows](/kit/agent/bot-urls/create/#how-many-urls-a-server-allows) | ## Plans and versions | Item | Rule | |---|---| | Plans on sale | Plus ($10 per month) and Pro ($25 per month); [Pricing](/foundation/pricing/) lists their limits | | Prices | US dollars per calendar month, excluding VAT. The API returns them in cents (`price_cents_per_month`) | | Plan versions | Each plan has a stable family (`family_id`) and one current version; each plan `id` is a version. When Hoody changes a plan's price or resources, it publishes a new version of that plan | | Your version | Your subscription stays on the version you bought: every renewal charges that version's price and keeps its resources and its hold period (`hold_days`), even after that version is no longer sold. To move to the current version, upgrade to it; that works when it keeps or raises every resource and the other [upgrade rules](#upgrade-rules) are met | | Catalogue and availability | A plan listed in the catalogue is not always available to buy: the quote says whether it is, in `available` | ## Regions `GET /api/v1/subserver-subscriptions/regions?plan_id=` (`hoody servers plans regions `) lists the regions where paid subservers are sold, for one plan, sorted by `region`. A plan that is retired, hidden or unknown is refused with `409 PLAN_NOT_AVAILABLE`. | Field | Meaning | |---|---| | `region` | The region's code. Pass it as `region` on the purchase quote and the purchase. Capitals and spaces around it are ignored | | `country`, `city` | Where the region is | | `available` | `true`: the plan can be bought there now. `false`: the region has no room for this plan right now; it stays listed. `available` does not count your [account limit](#account-limit); the quote does | | Rule | Detail | |---|---| | Automatic | A purchase without `region` lets Hoody pick a region that has room | | A chosen region is kept | With `region`, the subserver is placed there or the purchase is refused with `409 NO_PAID_CAPACITY_IN_REGION`, with nothing charged. It is never placed in another region | | No move | A subserver never changes region. An upgrade, a late payment and every renewal keep it where it is | | Where it is shown | `region` on the purchase quote and on the subscription ([subscription fields](#subscription-fields)), and `country`, `region` and `city` on the server | ## Quote fields `GET /api/v1/subserver-subscriptions/quote?plan_id=` (`hoody servers plans quote `) prices a purchase; add `region` (`--region `) to check one [region](#regions), or leave it out to let Hoody choose. `GET /api/v1/subserver-subscriptions/{id}/quote` prices an upgrade (`action=upgrade` with `plan_id`; `hoody servers subscriptions quote --action upgrade --plan-id `) or a late payment (`action=pay`; `hoody servers subscriptions quote --action pay`). | Field | Meaning | |---|---| | `charge_cents` | What the call would charge now. Pass it as `max_charge_cents` | | `price_cents_per_month` | Purchase quote only: the plan's monthly price. Upgrade and payment quotes omit this field; read the relevant plan or subscription for its monthly price | | `paid_through` | Upgrade quote: the end of the current paid period. Payment quote: the end of the month the payment would buy (the current one on a recovery). Purchase quote: the end of the first month | | `recovery` | Payment quote. `true` when the last payment's resume failed and its month is still running: `charge_cents` is 0, and paying again starts the subserver at no charge | | `available` | Purchase quote. `available: true`: you can buy the plan now. `available: false`: either no subserver of that size is free right now in the requested `region` (or anywhere, when you leave `region` out), or your account already holds as many paid subservers as its limit allows. Try another region, try again later, pick a smaller plan, or see [Account limit](#account-limit) | | `region` | Purchase quote: the region as `region`, `country` and `city`. With `region` sent, the one you chose. Without it, the region Automatic would pick right now, which can differ at purchase. It can be `null` | | `cap.max`, `cap.used`, `cap.reached` | Purchase quote: your paid subserver limit, how many you hold, and whether you are at the limit. `cap.used` is left out for an auth token restricted to realms | ## Account limit Your account can hold a limited number of paid subservers at once; each one is a separate server with its own subscription. `GET /api/v1/users/me` shows the limit and how many you have under `limits.paid_subservers`, and every purchase quote repeats them in `cap`. An auth token restricted to realms gets neither `limits.paid_subservers` nor `cap.used`; it reads `cap.reached` in the quote. A purchase over the limit is refused with `PAID_SUBSERVER_LIMIT_REACHED` and nothing is charged. Contact support to raise it. ## Charges and retries | Rule | Detail | |---|---| | Who pays | Buying, renewing, upgrading and paying a held subscription charge available [Referral credit](/foundation/wallet/referral-program/) first, then your General Balance. Add funds in [Billing & Payments](/foundation/billing/) | | Quote first | Quote before every purchase, upgrade or payment, and pass the quoted `charge_cents` as `max_charge_cents`, the ceiling on the debit. It is required whenever the charge is above 0 | | `idempotency_key` | Generate a new key for each new purchase, upgrade or payment. Sending the same key again returns the original operation and charges nothing more | | No answer | If a charge call gets no answer or a 5xx error, resend it with the same key, or read your subscriptions first: a purchase that went through shows as a new subscription, `provisioning` at first and `active` once it is ready. A new key is a new purchase | | After a refusal | When the purchase, upgrade or payment itself is refused (for example `PAID_SUBSERVER_LIMIT_REACHED`), the key stays refused: every later request with it returns the same refusal. Use a new key to try again. A request refused before it is accepted (a `401`, `403` or `429`, a subscription you cannot act on, or a pending account deletion) leaves the key unused, so you can retry with the same key | | Same key, different request | A different action, plan, region, subscription or `max_charge_cents` under a used key is refused with `409 IDEMPOTENCY_INTENT_MISMATCH`. Use a new key | | Scripts | Keep the key outside the script (an environment variable or a file) or print it before the charge, so a rerun after no answer reuses it instead of making a new one | | Buy panel in the Hub | To open checkout, select a plan under **Plans** in the Hub's **Plans & Billing**. The upgrade action the Hub shows on a server near or at its limit, **Get more room**, opens Plans, where you choose a plan before checkout. Nothing is bought before you select **Confirm purchase** (**Upgrade and pay** for an upgrade), and retrying the same request never charges twice | | Upgrade charge | Only the price difference, for the part of the current paid period that is left. The renewal date stays the same, and renewals then charge the new plan's price | | Late payment | Charges one month starting that day and moves the renewal day to that day. The months on hold are never charged. Follow the operation: if the resume fails, the subscription is `held` or `change_stuck`, and the paid month stays paid. A free retry is available when a fresh payment quote returns `recovery: true` and `charge_cents` 0: pay again with a new key. Contact support for `change_stuck` | | Refunds | Cancelling stops future renewals but does not refund the current period. If a purchase was charged but not delivered, contact support | ## Who can buy | Caller | Can buy, upgrade, pay and turn auto-renew on | |---|---| | You, signed in | Yes | | An auth token | Yes, with the `financial.subscriptions.purchase` permission, which also covers cancel and auto-renew. Listing, reading and quoting subscriptions, listing regions and reading operations need `financial.billing.read`; listing plans needs `financial.server_rental.view_marketplace` | | A session acting as another account | No: `403` "Only the account owner, signed in or with an auth token, can spend from this wallet." Turning auto-renew off and cancelling stay open | ## Upgrade rules An upgrade (`POST /api/v1/subserver-subscriptions/{id}/upgrade`) moves the subscription to a larger plan. It is refused, with nothing charged, when: | Code | Cause | What to do | |---|---|---| | `PLAN_CHANGE_NOT_UPGRADE` | The target plan would lower a resource in its `resources` (CPU, RAM, disk, disk speed, network speed, computers, snapshots or the AI multiplier), the alias limit (`max_proxy_aliases`), the Bot URL limit (`max_bot_urls`), the storage share limit (`max_storage_shares`), or the AI tier or allowance. `lower_fields` lists what it would lower (for example `max_storage_shares`, `ai_tier` or `ai_allowance`), or names `plan` when the target is the current plan | Pick a larger plan. There is no downgrade: to go smaller, buy a subserver on the smaller plan, move your computers to it with a [cross-server copy](/foundation/computers/copy-sync/#cross-server-copy), then cancel the bigger one | | `NO_PAID_CAPACITY` | The subserver grows where it is, and there is no room for the larger size | Try again later with a new `idempotency_key`, or buy a second subserver on the larger plan and move your computers to it | | `SUBSCRIPTION_REGION_FIXED` | The upgrade or its quote carried a `region` other than the subserver's own. `region` is optional there, and a subserver never changes [region](#regions) | Leave `region` out, or send the subserver's own, and retry with a new `idempotency_key`. To move, buy a subserver in the other region, move your computers to it with a [cross-server copy](/foundation/computers/copy-sync/#cross-server-copy), then cancel this one | | `SUBSCRIPTION_PERIOD_ENDED` | An upgrade needs time left in the current period, and `paid_through` has passed | Wait for the renewal to go through, or pay it if the subserver goes on hold, then upgrade | During an upgrade the subserver's computers are stopped, the subserver is resized, and each computer returns to its earlier state: running computers start again, stopped ones stay stopped. Its ID, computers and data stay. If the upgrade operation ends `failed`, read the subscription. It may be active on the old plan or in `change_stuck`. Contact support with the operation ID about the state and charge. ## Subscription fields `GET /api/v1/subserver-subscriptions` (`hoody servers subscriptions list`) lists your paid subservers; `GET /api/v1/subserver-subscriptions/{id}` (`hoody servers subscriptions get `) reads one. | Field | Meaning | |---|---| | `server_id` | The subserver's ID, to use as the server when you create a computer once `state` is `active`. It starts `null` and may be set while the subscription is still `provisioning`; it is `null` again after close | | `server_name` | The subserver's own name | | `region` | The subserver's [region](#regions), as `region`, `country` and `city`. It is set from the purchase on, including while `server_id` is still `null` during provisioning. It is `null` after a failed delivery or after close, and can be `null` after an Automatic purchase | | `state` | See [Subscription states](#subscription-states) | | `plan_id`, `plan` | The plan version billed at renewal, with its limits | | `anchor_day` | The current renewal day of the month. Initially this is the purchase day; a late payment moves it to the payment day. In a shorter month, the period ends on the month's last day, then returns to the anchor day in a month that has it | | `auto_renew` | `true` from purchase: shortly before each paid period ends, the month's price is charged and `paid_through` moves one month ahead. The new period starts when the current one ends | | `paid_through` | The end of the paid period | | `delete_at` | On a held, unpaid subscription: the moment permanent deletion begins. `null` otherwise | | `active_operation_id` | The operation in progress, if any | ## Subscription states | `state` | Meaning | |---|---| | `provisioning` | Bought and being delivered; `server_id` starts `null` and may be set before delivery ends. Wait for `active` before you create computers on it | | `active` | Delivered and running | | `past_due` | The paid period ended without a renewal, and the subserver is going on hold | | `held` | On hold: computers stopped, data kept until `delete_at` | | `wiping` | Being permanently deleted. It can no longer be paid, and nothing can be recovered | | `delivery_failed` | Delivery did not complete after the charge. Contact support with the subscription ID | | `change_stuck` | A change to the subserver has not finished. Contact support with the subscription ID | | `terminated` | Closed, or permanently deleted after an unpaid hold | | `host_wiped` | Deleted (older records only) | While the subscription is not active (being delivered, on hold, being changed or being deleted), calls that change its computers return `SUBSERVER_DORMANT`. Once the paid period ends and renewal is pending, new computers and copies are also refused until renewal completes. ## Operations A purchase, upgrade or payment answers `202` with an operation to poll; delivery of a new subserver runs after the charge. Read it with `GET /api/v1/subserver-operations/{id}` or `hoody servers jobs get `. | Field | Meaning | |---|---| | `kind` | What the operation does. Kinds include `purchase`, `upgrade`, `resume`, `hold` and `wipe` | | `result` | `null` while it runs, then `succeeded`, `failed` or `superseded`. A purchase with `result: succeeded` leaves the subscription `active` with `server_id` set; one with `result: failed` leaves it `delivery_failed` or `change_stuck`. After a failed upgrade, the subscription is active on its old plan or `change_stuck`. After a failed resume, it is `held` or `change_stuck` (see [Late payment](#charges-and-retries)). Contact support for `change_stuck` | | `charge_cents` | What the operation charged | ## Renewal notices Hoody notifies you before each renewal, including when your balance will not cover it, when the subserver goes on hold, before permanent deletion (`delete_at`), and when it has been deleted. Each notice is an in-app notification, usually with an email to your verified address. A hold that reaches deletion one day or less after it starts gets no separate reminder before deletion. ## Troubleshooting | Symptom or code | Cause | What to do | |---|---|---| | The quote says `available: false` | No subserver of that size is free in the requested region (or anywhere, when you left `region` out), or your account is at its paid subserver limit | Check `cap.reached`. If it is `true`, see [Account limit](#account-limit). If it is `false`, try another region, try again later or pick a smaller plan. Realm-limited tokens do not receive `cap.used` | | `INSUFFICIENT_BALANCE` (400) | Your Referral credit and General Balance together do not cover the charge: the first month, on a purchase. `data.required_cents` is the charge. Nothing was charged | Add funds in [Billing & Payments](/foundation/billing/) and retry with a new `idempotency_key` | | `CHARGE_CONFIRMATION_REQUIRED` (409) | The request carried no `max_charge_cents`. Nothing was charged | Quote, confirm the amount, and retry with `max_charge_cents` and a new `idempotency_key` | | `CHARGE_EXCEEDS_MAX` (409) | The current charge exceeds your supplied `max_charge_cents`. Nothing was charged | Quote again, confirm the new amount, and retry with the new `max_charge_cents` and a new `idempotency_key` | | `PAID_SUBSERVER_LIMIT_REACHED` (409) | The account holds as many paid subservers as its limit allows | See [Account limit](#account-limit) | | `PLAN_NOT_AVAILABLE` (409) | The plan version is retired, hidden or unknown | Pick a plan from the plan list | | `NO_PAID_CAPACITY` (409) on a purchase | No room for this plan right now. Nothing was charged | Try again later with a new `idempotency_key`, or pick a smaller plan | | `NO_PAID_CAPACITY_IN_REGION` (409) | The region you chose has no room for this plan right now. Nothing was charged, and the subserver is not placed anywhere else | List the [regions](#regions) and pick an available one, or leave `region` out, and retry with a new `idempotency_key` | | `PAID_REGION_UNKNOWN` (400) | `region` is not the code of a region where paid subservers are sold. Nothing was charged | Take a `region` code from the [region list](#regions) and retry with a new `idempotency_key` | | `SUBSCRIPTION_REGION_FIXED` (409) | An upgrade or its quote named a `region` other than the subserver's own. Nothing was charged | Leave `region` out and retry with a new `idempotency_key`: a subserver never changes region ([upgrade rules](#upgrade-rules)) | | `NO_PAID_CAPACITY` (409) on an upgrade | No room to grow this subserver right now. Nothing was charged | Try again later with a new `idempotency_key`, or buy a subserver on the larger plan and move your computers to it | | `HOST_UNAVAILABLE` (409) | The subserver cannot be changed or resumed right now. Nothing was charged | Try again later with a new `idempotency_key` | | `IDEMPOTENCY_INTENT_MISMATCH` (409) | The key was already used for a different request (action, plan, region, subscription or ceiling). Sending the same key with another `region`, or with `region` added or removed, counts as different. Nothing was charged | Use a new key | | `SUBSCRIPTION_NOT_PAYABLE` (409) | A payment has no effect in the subscription's state, or it is closed | Read the subscription: a held one can be paid until its deletion starts, and an active one renews by itself | | `SUBSERVER_WIPE_IN_PROGRESS` (409) | The subserver is being permanently deleted | It can no longer be paid. Contact support | | `SUBSERVER_DORMANT` on a computer call | The subscription is not active: it is being delivered, changed, held or deleted; or, for new computers and copies, its paid period has ended and the renewal has not gone through yet | Wait for the change or the renewal to finish, or pay a held subscription to start it again | | The subscription shows `delivery_failed` | Delivery did not complete after the charge | Contact support with the subscription ID | The [Servers API](/api/servers/#paid-subserver-subscriptions) page lists every error code of each call. ## Plan a subserver | Practice | Why | |---|---| | Outgrow the free server | More computers, CPU, RAM and disk than the free server allows, with the same workflow: the subserver is one more server ID to deploy on | | Separate environments | One subserver for production, the free server for experiments. Each subserver's limits are its own, so one environment cannot use up the other's | | Steady monthly workloads | A fixed monthly price that renews by itself from Referral credit and the General Balance, with no rental end date to track while auto-renew is on | | Keep a month's price in reserve | Keep at least one month's price across your Referral credit and General Balance so renewals do not fail | | Choose the region before you buy | A subserver never changes region: pick the one near your users, or the one your data must stay in | | Upgrade at a quiet moment | Running computers restart; stopped computers stay stopped | | Back up off the subserver | Snapshots stay on the subserver and are deleted with it. Copy important computers to another server as an off-server backup. A held subserver must be paid and running again before its computers can be copied | ## API calls | Call | CLI | What it does | |---|---|---| | `GET /api/v1/subserver-plans` | `hoody servers plans list` | The plans you can buy | | `GET /api/v1/subserver-subscriptions/regions` | `hoody servers plans regions` | The regions where a plan can run, and whether each has room | | `GET /api/v1/subserver-subscriptions/quote` | `hoody servers plans quote` | Price and availability of one plan, in one region with `region` | | `POST /api/v1/subserver-subscriptions` | `hoody servers subscriptions buy` | Buy a paid subserver (charges the first month) | | `GET /api/v1/subserver-operations/{id}` | `hoody servers jobs get` | Progress of a purchase, upgrade or payment | | `GET /api/v1/subserver-subscriptions` | `hoody servers subscriptions list` | Your paid subservers | | `GET /api/v1/subserver-subscriptions/{id}` | `hoody servers subscriptions get` | One paid subserver | | `GET /api/v1/subserver-subscriptions/{id}/quote` | `hoody servers subscriptions quote` | Price an upgrade or a late payment | | `POST /api/v1/subserver-subscriptions/{id}/upgrade` | `hoody servers subscriptions upgrade` | Move to a larger plan | | `POST /api/v1/subserver-subscriptions/{id}/pay` | `hoody servers subscriptions pay` | Pay a held subscription and resume it | | `PUT /api/v1/subserver-subscriptions/{id}/auto-renew` | `hoody servers subscriptions autorenew enable` or `disable` | Turn auto-renew on or off | | `POST /api/v1/subserver-subscriptions/{id}/cancel` | `hoody servers subscriptions cancel` | Stop renewing at the end of the paid period |