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

On the VM gateway a transient failure 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. Without one, 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. retryable is the signal to branch on, and this request is worth sending again after a backoff.

{
  "error": "No sandbox host available",
  "retryable": true
}

Volumes on a deployment with no VOLUMES_TABLE. A 501 is a fact about the deployment. Retrying it will return the same thing forever.

{
  "error": "Volumes are not configured"
}

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 always 404s. The browser gateway proxies to a pool route that does not exist, so every well-formed request to a live session returns a 404 whose body is the plain-text string 404 Not Found served under a JSON content type. It will not parse as JSON. Do not build against it. 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.