Skip to content
sistemo.io beta
GitHub Docs Quickstart Request an invite

Quotas

GET /v1/quotas

Scope: read or full. Knowing your own ceiling is not a privileged operation, so a read-only key can ask.

Returns every limit on the account alongside what you are currently using. The second half is the useful one: a 403 quota_exceeded names the dimension that bound, but only this tells you how close you were and what to free.

curl -sS https://api.sistemo.io/v1/quotas \
  -H "Authorization: Bearer $SISTEMO_API_KEY"

{
  "tier": "free",
  "quotas": [
    { "name": "machines",   "used": 1,  "limit": 3,
      "description": "Machines that exist, stopped ones included. A machine in the error state is not counted." },
    { "name": "vcpus",      "used": 1,  "limit": 4,
      "description": "vCPU summed across those machines." },
    { "name": "memory_mb",  "used": 1024, "limit": 4096,
      "description": "Memory summed across those machines." },
    { "name": "storage_gb", "used": 10, "limit": 30,
      "description": "Every disk on your account in any state — machine root disks and data volumes alike." },
    { "name": "volumes",    "used": 0,  "limit": 2,
      "description": "Data volumes only. A machine's root disk counts towards storage_gb instead, so a detached root disk leaves this at zero." }
  ]
}
Field Meaning
tier free, payg or enterprise
name The dimension — the same word a quota_exceeded message uses
used Current consumption
limit The ceiling, including any per-account override
description What that dimension counts. Read it before filing a bug

The five dimensions are independent

A request must fit all five. They are not a single pool, so the one that blocks you is not always the one you expected:

  • Filling storage blocks both a new machine and a new volume — both need disk.
  • Filling vCPU blocks a machine but still lets you create a volume.
  • A stopped machine still counts towards machines, vcpus and memory_mb. Stopping saves money, not quota. Destroy it to get the quota back.
  • A machine in the error state counts towards none of them. It is waiting to be deleted, not to be restarted.

storage_gb and volumes count different things, and both numbers are right

Destroy a machine with ?preserve_storage=true and you can sit at storage_gb 10/30 and volumes 0/2 simultaneously. The kept root disk takes disk but does not occupy a data-volume slot. This looks like a bug and is not.

Defaults by tier

Per-account overrides can raise any of these; GET /v1/quotas always reports your effective limits, so treat this table as the starting point, not the answer.

machines vcpus memory_mb storage_gb volumes
free (trial) 3 4 4096 30 2
payg (after your first top-up) 20 24 32768 200 10

Adding a card unlocks the €25 trial bonus but keeps you on free limits. Only a real top-up moves you to payg. See Usage & billing.

Handling a refusal

A quota refusal is a 403 with code: "quota_exceeded", and it is fundamentally different from every other 403 on this API:

forbidden quota_exceeded
The credential Cannot do this Is fine
The request Is not allowed Is valid
Retrying Never works Works once you free the resource
What to do Use a full-scope key Stop/destroy something, or raise the limit 
from sistemo import Sandbox, QuotaExceededError

try:
    sb = Sandbox()
except QuotaExceededError as e:
    print("at capacity:", e.detail)   # names the dimension and the usage
    # …destroy an old sandbox, then retry. This is a retryable condition.
else:
    with sb:                          # closes the machine on the way out
        print(sb.run("uname -a").stdout)

Both SDKs raise a dedicated QuotaExceededError rather than folding it into AuthError, for exactly this reason — see Errors.

A message mentioning a fleet limit is not your quota

Occasionally a create is refused because the fleet itself is full rather than your account. Topping up will not lift that one. Retry shortly, or get in touch if it persists.