Exit Codes & Errors

Every exit code, error code, and status value the CLI emits — your branching contract for agents and CI.

Agents and CI branch on the exit code; the JSON error envelope adds detail. Exit codes and error codes won’t change within a major version. --help and --version exit 0.

Exit codes

Code	Meaning
0	Success
1	Run did not pass, a tunnel stop --all failure, or unhandled server error (INTERNAL)
2	Not yet implemented
3	Auth error: key missing, unparseable, revoked, or missing scope
4	Not found: ID doesn’t exist or belongs to another tenant; also a server too old for tunnel list / tunnel stop --all, and test failure get / test artifact get with no bundle (reason no_code or cancelled_no_artifacts)
5	Validation error: bad field, enum or --output value, payload too large, missing required flag, or flag-parse error. Includes --local with backend tests, local --max-concurrency above 10, and tunnel stop --all without --confirm
6	Conflict or precondition: snapshot or run already in flight, idempotency body mismatch, newer codeVersion, agent install blocked (target differs, no --force), or a tunnel precondition (tunnel-required, tunnel-offline, tunnel-otp-auth-unsupported, frontend-auth-target-origin-mismatch). Tunnel preconditions are refused before any charge; see Test an app on your machine
7	Wait timeout, or feature not on the current backend
8, 9	Reserved
10	Unavailable or transport failure: service down, tunnel not configured, or a tunnel disconnected, revoked, expired or taken over mid-run
11	Rate limited
12	Insufficient credits
13	FEATURE_GATED: the workspace’s plan doesn’t include the feature, or the workspace is paused (details.reason: "paused"). Not a missing scope, which is 3
14	Client too old: upgrade the CLI
129 / 130 / 143	SIGHUP / SIGINT (Ctrl-C) / SIGTERM while waiting. See Interrupts

Wait timeout (exit 7)

Before exiting, the CLI still prints { "runId": "...", "status": "running" } to stdout.

• Ordinary run: resume with testsprite test wait <run-id>.
• Run that owns its tunnel (automatic, or --local): the timeout cancels it by default and closes the tunnel, so start a new run with a longer --timeout. Cancellation is best-effort and the run may already be billed.
• Local batch: each run has its own timeout. A timeout (7) outranks failures (1) but not auth (3), conflict (6), transport (10), rate-limit (11) or credit (12) errors.

Interrupts and pipes

129, 130 and 143 are 128 + signal. A signal while polling an ordinary run (--wait, test wait, test flaky), or a --local run adopted with --tunnel-client, detaches: the run keeps executing and billing, stdout gets the partial running object, and stderr names the run:

Interrupted (SIGINT). Run run_5c1d9a2b is still executing on the server and will keep running (and billing) until it finishes.
  Re-attach with: testsprite test wait run_5c1d9a2b
  Cancel with:    testsprite test cancel run_5c1d9a2b

A run on a tunnel this command opened (automatic or --local) is cancelled on the same signals by default, because the tunnel closes with the process; --no-cancel-on-interrupt skips the cancel but the tunnel still closes. Details and refunds: Cancelling a Run.

With --output json, stderr carries an INTERRUPTED envelope with details.signal (not in the table below). A second signal exits immediately. If a reader closes a pipe early (... | head -n 1), the CLI exits 0.

Error codes

Code	HTTP	Exit	Retry
AUTH_REQUIRED / AUTH_INVALID	401	3	No
AUTH_FORBIDDEN	403	3	No. Text mode prints required: / granted: scopes
NOT_FOUND	404	4	No
VALIDATION_ERROR	400	5	No
PAYLOAD_TOO_LARGE	413	5	No
CONFLICT	409	6	Once after 1 s (not for cancel conflicts)
IDEMPOTENCY_BODY_MISMATCH	409	6	No: same key, different body
PRECONDITION_FAILED	412	6	No. Re-fetch codeVersion, attach or restore a tunnel, or use an environment without OTP
RATE_LIMITED	429	11	Honors Retry-After, 3 attempts
INSUFFICIENT_CREDITS	402	12	No: top up
FEATURE_GATED	403	13	No: change plan, or resume the paused workspace
CLIENT_TOO_OLD	426	14	No: upgrade
UNSUPPORTED	501	7	No
INTERNAL	500	1	Once
UNAVAILABLE	503	10	Exponential backoff, 4 attempts

RATE_LIMITED with details.reason=tunnel_binding_limit is a standing capacity refusal and is not retried: run testsprite tunnel list, then stop an unused binding or reuse one with --tunnel-client.

Error output

With --output json, errors are an envelope on stderr; text mode prints message and nextAction.

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Authentication is required.",
    "nextAction": "Run `testsprite setup`, or set TESTSPRITE_API_KEY and run `testsprite setup --from-env` for non-interactive flows.",
    "requestId": "req_2026_05_05_abc123",
    "details": {}
  }
}

Statuses

Test status is the outcome of the latest completed run: draft (no code yet), ready (has code, never run), queued, running, passed, failed (includes infra crash), blocked (rejected before a real verdict), unknown. cancelled is never emitted at test level; cancelling leaves the previous status.

Run status: queued, running (non-terminal); passed, failed, blocked, cancelled (terminal). Step status: passed, failed, or null (not executed).

Run source: cli (including test rerun), portal, mcp, schedule, github_action.

Retrying safely

Reuse --idempotency-key on write commands so retries are deduplicated server-side (why). Retry only exits 6 (CONFLICT), 10 and 11; for the others fix the cause first (check the ID, fix the input, top up credits, change plan). For tunnel-required, drop --no-wait or pass --local; tunnel-offline needs a live binding.

Where to Go Next

Command Reference

Every command and flag

CI/CD Integration

Gate pipelines on exit codes