Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Lookup tables for paid subservers. Every plan and subscription call is in the Servers API.

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.

LimitPlan fieldWhat counts
CPU and RAMresources.cpu_cores, resources.ram_gbThe 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
Diskresources.disk_limit_gbOne disk quota shared by every computer on the subserver
Disk speedresources.disk_io_read_mib, resources.disk_io_write_mibReads and writes are each limited to the plan’s disk speed
Network speedresources.network_limit_mbpsThe plan sets a speed, not a volume. There is no traffic quota (see network fair use)
Computersresources.max_computersEvery 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
Snapshotsresources.snapshots_per_computerEach computer can keep up to the plan’s number of snapshots
Aliasesmax_proxy_aliasesThe proxy aliases of every computer on the subserver, disabled and expired ones included. At the limit, delete an alias or upgrade
Bot URLsmax_bot_urlsThe 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 sharesmax_storage_sharesThe 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
ProcessesnoneAt 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 AIai_tier, resources.ai_multiplierai_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.

Limit reachedWhat you getWhat to do
AliasesCreating 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 createdDelete an alias on that subserver, or follow data.upgrade when the error carries it, as for the computer limit. See Alias limit reached
Bot URLsCreating another Bot URL, or moving one onto the subserver, is refused with 400 SERVER_BOT_URL_LIMIT, and data carries max and used. Nothing changesDelete 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
ItemRule
Plans on salePlus ($10 per month) and Pro ($25 per month); Pricing lists their limits
PricesUS dollars per calendar month, excluding VAT. The API returns them in cents (price_cents_per_month)
Plan versionsEach 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 versionYour 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 availabilityA plan listed in the catalogue is not always available to buy: the quote says whether it is, in available

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.

FieldMeaning
regionThe region’s code. Pass it as region on the purchase quote and the purchase. Capitals and spaces around it are ignored
country, cityWhere the region is
availabletrue: 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
RuleDetail
AutomaticA purchase without region lets Hoody pick a region that has room
A chosen region is keptWith 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 moveA subserver never changes region. An upgrade, a late payment and every renewal keep it where it is
Where it is shownregion on the purchase quote and on the subscription (subscription fields), and country, region and city on the server

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).

FieldMeaning
charge_centsWhat the call would charge now. Pass it as max_charge_cents
price_cents_per_monthPurchase 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_throughUpgrade 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
recoveryPayment 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
availablePurchase 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
regionPurchase 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.reachedPurchase 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

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.

RuleDetail
Who paysBuying, renewing, upgrading and paying a held subscription charge available Referral credit first, then your General Balance. Add funds in Billing & Payments
Quote firstQuote 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_keyGenerate a new key for each new purchase, upgrade or payment. Sending the same key again returns the original operation and charges nothing more
No answerIf 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 refusalWhen 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 requestA different action, plan, region, subscription or max_charge_cents under a used key is refused with 409 IDEMPOTENCY_INTENT_MISMATCH. Use a new key
ScriptsKeep 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 HubTo 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 chargeOnly 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 paymentCharges 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
RefundsCancelling stops future renewals but does not refund the current period. If a purchase was charged but not delivered, contact support
CallerCan buy, upgrade, pay and turn auto-renew on
You, signed inYes
An auth tokenYes, 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 accountNo: 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

An upgrade (POST /api/v1/subserver-subscriptions/{id}/upgrade) moves the subscription to a larger plan. It is refused, with nothing charged, when:

CodeCauseWhat to do
PLAN_CHANGE_NOT_UPGRADEThe 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 planPick 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_CAPACITYThe subserver grows where it is, and there is no room for the larger sizeTry again later with a new idempotency_key, or buy a second subserver on the larger plan and move your computers to it
SUBSCRIPTION_REGION_FIXEDThe upgrade or its quote carried a region other than the subserver’s own. region is optional there, and a subserver never changes regionLeave 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_ENDEDAn upgrade needs time left in the current period, and paid_through has passedWait 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.

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.

FieldMeaning
server_idThe 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_nameThe subserver’s own name
regionThe 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
stateSee Subscription states
plan_id, planThe plan version billed at renewal, with its limits
anchor_dayThe 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_renewtrue 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_throughThe end of the paid period
delete_atOn a held, unpaid subscription: the moment permanent deletion begins. null otherwise
active_operation_idThe operation in progress, if any
stateMeaning
provisioningBought and being delivered; server_id starts null and may be set before delivery ends. Wait for active before you create computers on it
activeDelivered and running
past_dueThe paid period ended without a renewal, and the subserver is going on hold
heldOn hold: computers stopped, data kept until delete_at
wipingBeing permanently deleted. It can no longer be paid, and nothing can be recovered
delivery_failedDelivery did not complete after the charge. Contact support with the subscription ID
change_stuckA change to the subserver has not finished. Contact support with the subscription ID
terminatedClosed, or permanently deleted after an unpaid hold
host_wipedDeleted (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.

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>.

FieldMeaning
kindWhat the operation does. Kinds include purchase, upgrade, resume, hold and wipe
resultnull 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_centsWhat the operation charged

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.

Symptom or codeCauseWhat to do
The quote says available: falseNo 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 limitCheck 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 chargedAdd funds in Billing & Payments and retry with a new idempotency_key
CHARGE_CONFIRMATION_REQUIRED (409)The request carried no max_charge_cents. Nothing was chargedQuote, 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 chargedQuote 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 allowsSee Account limit
PLAN_NOT_AVAILABLE (409)The plan version is retired, hidden or unknownPick a plan from the plan list
NO_PAID_CAPACITY (409) on a purchaseNo room for this plan right now. Nothing was chargedTry 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 elseList 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 chargedTake 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 chargedLeave region out and retry with a new idempotency_key: a subserver never changes region (upgrade rules)
NO_PAID_CAPACITY (409) on an upgradeNo room to grow this subserver right now. Nothing was chargedTry 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 chargedTry 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 chargedUse a new key
SUBSCRIPTION_NOT_PAYABLE (409)A payment has no effect in the subscription’s state, or it is closedRead 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 deletedIt can no longer be paid. Contact support
SUBSERVER_DORMANT on a computer callThe 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 yetWait for the change or the renewal to finish, or pay a held subscription to start it again
The subscription shows delivery_failedDelivery did not complete after the chargeContact support with the subscription ID

The Servers API page lists every error code of each call.

PracticeWhy
Outgrow the free serverMore 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 environmentsOne 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 workloadsA 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 reserveKeep at least one month’s price across your Referral credit and General Balance so renewals do not fail
Choose the region before you buyA subserver never changes region: pick the one near your users, or the one your data must stay in
Upgrade at a quiet momentRunning computers restart; stopped computers stay stopped
Back up off the subserverSnapshots 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
CallCLIWhat it does
GET /api/v1/subserver-planshoody servers plans listThe plans you can buy
GET /api/v1/subserver-subscriptions/regionshoody servers plans regionsThe regions where a plan can run, and whether each has room
GET /api/v1/subserver-subscriptions/quotehoody servers plans quotePrice and availability of one plan, in one region with region
POST /api/v1/subserver-subscriptionshoody servers subscriptions buyBuy a paid subserver (charges the first month)
GET /api/v1/subserver-operations/{id}hoody servers jobs getProgress of a purchase, upgrade or payment
GET /api/v1/subserver-subscriptionshoody servers subscriptions listYour paid subservers
GET /api/v1/subserver-subscriptions/{id}hoody servers subscriptions getOne paid subserver
GET /api/v1/subserver-subscriptions/{id}/quotehoody servers subscriptions quotePrice an upgrade or a late payment
POST /api/v1/subserver-subscriptions/{id}/upgradehoody servers subscriptions upgradeMove to a larger plan
POST /api/v1/subserver-subscriptions/{id}/payhoody servers subscriptions payPay a held subscription and resume it
PUT /api/v1/subserver-subscriptions/{id}/auto-renewhoody servers subscriptions autorenew enable or disableTurn auto-renew on or off
POST /api/v1/subserver-subscriptions/{id}/cancelhoody servers subscriptions cancelStop renewing at the end of the paid period