Agent? Fetch sharkmagic.si/docs/llms.txt or this page as markdown

Errors#

Every /v1 error has the same body, a stable code, and says whether a retry can succeed.

{"error": {
  "code": "lease_cap_reached",
  "message": "too many leases running: tenant cap reached; the command did not start",
  "retryable": true,
  "request_id": "req_01M6N8R52A3XZP6Z2DTKWFNRRW",
  "details": {"scope": "tenant", "limit": 6, "active": 6, "queued": 1, "waited_ms": 30012}
}}

• code is stable; branch on it. The list is open: treat an unknown code by its HTTP status.
• message is for humans and may change.
• retryable: true means the same request may succeed later. Retryable 429 and 503 always carry a Retry-After header (integer seconds, 1–30), computed from your queue rather than fixed.
• request_id is also in the Shark-Request-Id header of every response, errors or not. Quote it when you ask for help.
• details carries the field at fault (details.field), limits (limit, used, max_s) or a scope.

A command that fails is not an HTTP error. exec answers 200 with the command's exit; check shark_status for Shark-side outcomes (conflict, timeout, infra_timeout, infra_error, signaled: concepts.md).

A busy node is not an infra error. When the node's CPUs are saturated it refuses new work up front (503 out_of_capacity, details.reason = cpu_pressure or cpu_runqueue), and a command it admitted but could not start in time (its VM got no CPU to boot) ends as shark_status: "capacity_unavailable", not infra_error. In both cases the command did not run: resend it with the same op_id after Retry-After. A sync exec gets that second case as 503 capacity_unavailable (details.reason = lease_start, details.op_id); a stream or an async op gets it in the result (exit 125, "retryable": true, "retry_after_s"). The CLI and both SDKs retry both on their own. To see whether a node is admitting work right now: the node_admission row of GET /v1/quotas (state open or closed, reason, the CPU pressure it read).

Codes#

Warnings (in a 2xx body, warnings: [{secret, code, message}]; the request succeeded):

Secrets routes also answer 400 invalid_request with details.field = secrets.NAME.apply (apply is all or ref, account secrets only) or secrets.NAME.ref (ref is "account", a Space's secrets only, with no value), and 422 unsupported on a node without the sealed store.

SDK-only codes (raised by the SDKs, never sent by the API): wait_timeout (Python op.wait(timeout=…) ran out of time; the command keeps running), command_failed, infra_error, connection, config (sdk-python.md).

Lines Shark adds to a command's output#

A command that ran (or was refused before it started) may end with one shark: line on stderr from Shark itself. They are meant for coding agents as much as for people: one line, what happened, the next step.

Inside shark code, commands also get $SHARK_MODE (devbox), $SHARK_SPACE and $SHARK_CONTEXT (JSON: what works in this session); shark context --json prints it. See shark-code.md.

Retrying safely#

The rule: a retried request never does the work twice, and never silently does another request's work.

1. Give every command an op_id and every create/fork an Idempotency-Key. Reuse it only for the same request.
2. Retry on connection errors, on 5xx, and on any error with "retryable": true, after Retry-After when present (otherwise exponential backoff with jitter, from 0.5 s, capped at 30 s).
3. Do not retry 4xx with "retryable": false; fix the request.
4. A retried DELETE that answers 404 means your first attempt worked.

The CLI and both SDKs already do all four. The SDK error classes map one-to-one to the codes (Python: RateLimitError, LeaseCapError, QuotaExceededError, CreditsExhaustedError, IdempotencyMismatchError, NotFoundError, UnsupportedError, …; each has .code, .status, .retryable, .retry_after, .request_id, .details).

Streams#

On an SSE stream (exec with Accept: text/event-stream, /ops/{op_id}/events), the last event is always exit or error; an error event carries {"code", "message"} with the codes above. A stream that drops before either is not an error: reconnect to /ops/{op_id}/events with Last-Event-ID and you get the rest, each event once.