Errors

How both gateways report failure on the wire: the body shape, every status they return, every machine-readable code, and which failures are worth retrying. This page is the HTTP contract; no SDK code appears on it. For the client-side error types that wrap these responses, see the SDK reference.

Contents

• Error body
• Status codes
• Code values
• Retry semantics, including what the SDKs do
• Errors on the wire
• Traps

Error body

Every error from either gateway is a JSON object with a human-readable error. Some handlers add a machine-readable code. Branch on the status or on code, never on the prose. The prose is not stable across releases.

Individual errors carry extra context alongside these: plan, cap, feature, limit, supported, profileId. They are documented on the endpoints that emit them in the API reference. The object is open: treat unknown fields as additive.

{
  "code": "ConcurrencyLimitExceeded",
  "error": "Concurrent session limit reached (20)",
  "plan": "starter",
  "cap": 20
}

Status codes

Successes are 200, except 201 on create, 202 on an async template build, 204 on browser release, and 101 on a WebSocket upgrade. A VM exec whose command exits non-zero is still 200. The call succeeded, the command failed. Read exitCode.

Code values

The complete set. Fifteen values across the two gateways; a handler that does not set one leaves code absent, so always tolerate its absence.

Retry semantics

502, 503, 504, 507 (VM gateway only) and transport errors (connection reset, DNS failure, timeout) are the retryable class: an upstream was unreachable or capacity was briefly unavailable, and the same request may well succeed a moment later. Back off with jitter. Everything in the 4xx range is deterministic. The same request will fail the same way until you change the request, the plan, or the resource state.

A transient failure on either gateway also carries "retryable": true in the body. Prefer that signal over the bare status. Send Idempotency-Key: <uuid-v4> on create routes to make the retry safe: the gateway remembers the first 2xx per (org, key) for 24 hours and replays it byte-for-byte, same sandboxId/sessionId, with the response header Idempotent-Replayed: true. The same key with a different route or body is 409 IdempotencyKeyReused; failures (including 429) are not remembered, so a retry really retries. Without a key, a retried create can double-charge you a VM. GET and DELETE are idempotent by nature: deleting an already-gone VM still returns 200 {"ok": true}.

What the SDKs do

The two clients do not share a retry policy. If you are writing against the wire directly, this is the behaviour you are replacing.

Errors on the wire

A bad key on the browser gateway. The body is the minimal envelope: error and nothing else.

curl -sS -i https://api.getsolari.com/profiles \
  -H "Authorization: Bearer slr_live_not_a_real_key"

HTTP/1.1 401 Unauthorized
content-type: application/json

{"error":"Unauthorized"}

A capacity failure on the VM gateway — a valid request, no host free to place it on right now. retryable is the signal to branch on, and this is worth sending again after a backoff; the SDKs already do.

{
  "code": "InsufficientCapacity",
  "error": "No host currently has room for a sandbox this size. Your request is valid — the fleet is busy right now — so retrying should succeed as capacity frees up.",
  "hint": "Retry with the same spec. A smaller cpu/memMb will fit sooner if you need to start immediately.",
  "retryable": true
}

{
  "code": "ValidationError",
  "error": "cpu must be 8 or less (asked for 16)",
  "field": "cpu"
}

A create with a non-empty volumes[], on a host pool that doesn’t carry the gcsfuse mount build yet. Today that’s any desktop — volumes work on sandboxes in every isolation mode. Unlike a platform-fact 501, this is a 409 because the missing piece is which host pool you land on: a different pool, or the same pool after its next rebake, can succeed.

{
  "code": "HostCapabilityMissing",
  "error": "does not support: volumes.mount",
  "missingCapabilities": ["volumes.mount"]
}

Branch on the status first, then on code. Capturing the body and the status separately keeps both available:

STATUS=$(curl -sS -o /tmp/resp.json -w '%{http_code}' \
  -X POST https://api.getsolari.com/sandboxes \
  -H "Authorization: Bearer $SOLARI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"template":"base","cpu":2,"memMb":2048}')

case "$STATUS" in
  2*)         jq -r .sandboxId /tmp/resp.json ;;
  429)        echo "at cap: pause or kill a session, retrying will NOT help" ;;
  502|503|504) echo "transient: resend with the SAME Idempotency-Key" ;;
  *)          jq -r '"\(.code // "no-code"): \(.error)"' /tmp/resp.json ;;
esac

Traps

• GET /sessions/:id answers from gateway state, not the browser. status is one of active, released, expired, unknown. A released session was ended by DELETE /sessions/:id or server-side (client disconnected); polling for it is the supported way to confirm a release. unknown means the owning pool is not registered on the replica that answered, so liveness cannot be confirmed; it is not a failure. A well-formed id from your own org never 404s. See the endpoint's entry.
• A 404 on release is not a no-op. DELETE /sessions/:id acks 204 even for an already-released session, so a 404 (InvalidSessionId) there means the release did not happen. Do not treat it as success.
• Not every 5xx is transient. 501 is a configuration fact and 500 is a bug; only 502/503/504 reliably reward a retry.
• A revoked key can keep working for up to 60 seconds. The browser gateway caches verified bearers, so revocation is not instant unless the control plane invalidates it first.
• A 200 from exec does not mean your command worked. The HTTP call succeeded; the command's own exitCode is in the body.

For the routes these errors come from, see the API reference. If you hit an error that isn't listed here, or one whose behaviour doesn't match this page, email hello@getsolari.com.