Paid Subservers reference
Section titled “Paid Subservers reference”Lookup tables for paid subservers. Every plan and subscription call is in the Servers API.
Plan limits
Section titled “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) |
| 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 |
| Snapshots | resources.snapshots_per_computer | Each computer can keep up to the plan’s number of snapshots |
| Aliases | max_proxy_aliases | The 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 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 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 |
Once your account has held a paid subserver of any plan, it can use up to 50 realms and keeps that limit after the subserver ends. The limit applies to the whole account, not to the subserver.
At a limit
Section titled “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 |
| 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 |
Plans and versions
Section titled “Plans and versions”| Item | Rule |
|---|---|
| Plans on sale | Plus ($10 per month) and Pro ($25 per month); 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 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
Section titled “Regions”GET /api/v1/subserver-subscriptions/regions?plan_id= (hoody servers plans regions <plan-id>) 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; 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), and country, region and city on the server |
Quote fields
Section titled “Quote fields”GET /api/v1/subserver-subscriptions/quote?plan_id= (hoody servers plans quote <plan-id>) prices a purchase; add region (--region <code>) to check one region, 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 <id> --action upgrade --plan-id <plan-id>) or a late payment (action=pay; hoody servers subscriptions quote <id> --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 |
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
Section titled “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
Section titled “Charges and retries”| Rule | Detail |
|---|---|
| Who pays | Buying, renewing, upgrading and paying a held subscription charge available Referral credit first, then your General Balance. Add funds in Billing & Payments |
| 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
Section titled “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
Section titled “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, 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 | 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, 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
Section titled “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 <id>) 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, 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 |
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
Section titled “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
Section titled “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 <id>.
| 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). Contact support for change_stuck |
charge_cents | What the operation charged |
Renewal notices
Section titled “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
Section titled “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. 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 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 |
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 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 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) |
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 page lists every error code of each call.
Plan a subserver
Section titled “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
Section titled “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 |