Errors¶

{ "detail": "Machine quota exceeded (limit 1).", "code": "quota_exceeded" }

Authentication failures carry no code at all

This is the one case where branching on code does not work, and it is worth knowing before you write the handler. Auth and scope refusals are produced by middleware that runs before the handler layer, and it emits detail only:

What happened	Status	Exact body
Key missing, malformed or revoked	401	{"detail":"invalid API key"}
A read key on a mutating route	403	{"detail":"this API key is read-only; a full-scope key is required for this action"}

So err.code is undefined/None for both. Branch on the status for these two, and on code for everything else. The SDKs already do this: a 401, or a 403 whose code is not quota_exceeded, becomes an AuthError.

⚠ Earlier versions of this page listed invalid_api_key and forbidden_scope as codes, and machine_not_running for a 409. None of those three are ever sent. If your error handling branches on them, it has never fired — use the table above.

from sistemo import Sandbox, QuotaExceededError, AuthError

try:
    sb = Sandbox()
except QuotaExceededError as e:      # first — it is the narrower case
    print("free something and retry:", e.detail)
except AuthError as e:               # second
    print("credential problem:", e.detail)
else:
    with sb:                         # closes the machine on the way out
        print(sb.run("uname -a").stdout)