Errors

{
  "error": {
    "code": "limit_reached",
    "message": "The Free plan runs 1 machine at a time, and dev is already running. Suspend one or upgrade.",
    "retryable": false,
    "retry_after_seconds": null,
    "docs_url": "https://tryquivvo.com/docs/errors#limit_reached",
    "request_id": "req_...",
    "owner_action": { "url": "https://tryquivvo.com/app/billing", "message": "Upgrade from the Free plan to run more machines at once." }
  }
}

The CLI turns these into exit codes. Under --json every error is one document on stdout, with the same fields plus exit_code, status and hint. The MCP server returns the same fields as JSON text with isError set.

bad_request

HTTP 400. CLI exit 2. Don't retry as it is.

The request is wrong: a bad field, a size that isn't allowed, a missing X-Confirm-Delete header, or an upload over 4 MB. The message says what to change.

unauthorized

HTTP 401. CLI exit 3. Don't retry as it is.

There's no key, or it's invalid or was revoked. Sign in again with quivvo login --agent --no-wait --json, or check QUIVVO_API_KEY. See agent sign-up.

forbidden

HTTP 403. CLI exit 3. Don't retry as it is.

This key doesn't have the scope, a read-only key asked for a path it can't read (/proc, /sys, /dev, /run or the daemon's own state), the route needs someone signed in on the dashboard, as billing does, or a signed-in browser's request came from another site. GET /api/v1/whoami lists the scopes a key has. owner_action says what the owner can do.

not_found

HTTP 404. CLI exit 4. Don't retry as it is.

There's no such machine, snapshot, job or file in this workspace. quivvo ls shows the machines it has.

conflict

HTTP 409. CLI exit 75 when retryable, otherwise 1. From exec, run and sh, 125.

The name is taken, the machine is between states or still being created, its CPU or memory can't change while it runs, a snapshot isn't ready, a disk is still being copied from what you're deleting, or an Idempotency-Key was reused for a different request, including the same route with a different body. When retryable is true, the machine is between states and will settle: try again. Otherwise the message says what to change.

limit_reached

HTTP 403. CLI exit 5. Don't retry as it is.

A plan limit: machines running at once, machines kept, size, disk, snapshots, how long a machine may stay awake, active keys, webhooks, or published ports on a machine. The message names the limit and what's in the way. Make room with what you're allowed to do: suspend or delete a machine, or delete a snapshot. The CLI's hint names the commands. A request that's wrong in itself, such as a bad name or a name already taken, gets that error first and never this one. Upgrading is for the owner: pass on owner_action.

insufficient_credits

HTTP 402. CLI exit 5. Don't retry as it is.

The credit balance is empty, so machines can't run. Only the owner can add credit, on the dashboard: pass on owner_action. API keys can't reach billing.

queued

HTTP 403. CLI exit 5. Don't retry as it is.

This workspace is waiting in the queue, so it can't create or fork machines yet. The message gives its place. Only the owner can move it: pass on owner_action, which holds their invite link. Each person who signs up with the link moves them up 10 places, and a paid plan skips the queue. quivvo queue and GET /queue show the same.

machine_not_running

HTTP 409. CLI exit 75 when retryable, otherwise 1, or 125 from exec, run and sh.

The machine isn't running, and nothing ran. With retry_after_seconds it's on its way up: try again, as the CLI does by itself. Without it, it stays down until asked: run quivvo start or quivvo resume, or for a machine in failed, quivvo restart. The MCP server's read tools answer this for any machine that isn't running, because they don't wake machines, and so does the REST API for a key with no machines:write.

provider_error

HTTP 502. CLI exit 75 when retryable, otherwise 1. From exec, run and sh, 125.

The machine's host, or its daemon, didn't do what was asked. The command may or may not have run, so check before repeating anything that changes things. quivvo logs shows what's known about a machine, whatever its state.

A snapshot or fork that the provider won't copy ends here too. In that case nothing was created, and the source is untouched.

capacity

HTTP 503. CLI exit 75. Retry after retry_after_seconds.

There's no room right now, on our side or the provider's. On a create, nothing was created: try another region with --region, or try again in a few minutes. On a start or resume, the machine and its disk are where they were, and no other host in its region had room either: try again in a few minutes.

rate_limited

HTTP 429. CLI exit 75. Retry after retry_after_seconds.

Too many requests, such as more than 30 feedback reports in an hour, more than 600 commands or 1,200 changes of any kind a minute in a workspace, more machines created in an hour than a plan allows (60 on Free), or too many sign-ins started from one address. Nothing happened. Wait and send it again. A sign-in that's already pending doesn't count: run the same login again and it reuses its code.

internal

HTTP 500. CLI exit 75 when retryable, otherwise 1. From exec, run and sh, 125.

Something went wrong on our side. The request may or may not have taken effect, so check first if repeating it would matter. If it keeps happening, report it with the request_id: quivvo feedback "what happened".

authorization_pending

HTTP 400, while polling POST /api/v1/auth/device/token. quivvo login --agent --no-wait exits 75.

The owner hasn't decided yet. Try again later, no sooner than every interval seconds. An agent should end its turn rather than wait.

access_denied

HTTP 400, while polling. quivvo login exits 77.

The owner refused this sign-in. Ask them before trying again. Nothing was created.

expired_token

HTTP 400, while polling. quivvo login exits 76.

The code expired before anyone approved it, or this sign-in was already completed. Agent codes last 24 hours and CLI codes 15 minutes. Run the command again for a new code.

What other codes can the CLI report?

Under --json, a failure that never reached the API has a code of its own:

exec, run, ssh, jobs wait and jobs logs -f pass on the remote command's exit code, which can be any of these numbers too. Under --json, the error key is what tells them apart.