Exit codes

Code	Name	Meaning	Common causes
0	Success	Command completed	—
1	Generic	Unmapped failure	Server returned 500 with an unrecognised code; CLI internal panic recovery
2	Usage	Bad input / failed pre-flight	Missing required flag, malformed JSON spec, workflow validation rule violation, --key / --value cardinality mismatch, invalid HTTP header value from env, HTTP 400
3	Auth	Not logged in OR token expired and refresh failed	ATHENA_API_TOKEN empty, no credentials.toml, server refresh endpoint returned 401, HTTP 401
4	NotFound	Resource doesn’t exist	Slug/ID doesn’t match any agent, workspace, or group; HTTP 404
5	Conflict	Optimistic-lock failure or duplicate	Draft expected_updated_at doesn’t match server; named draft with that name already exists; HTTP 409
6	RateLimited	Too many requests	Per-workspace concurrency cap hit; HTTP 429 (check Retry-After)
7	Unreachable	Network or transport failure	DNS failure, TLS error, SSE chunk decode error, SSE buffer exceeded 64 KiB, HTTP 503
8	PaymentRequired	Workspace credits exhausted	agent run rejected at preflight; HTTP 402
9	ExecutionFailed	Workflow ran but exited with failure	status: failed, stream_lost (connection closed without terminal event), any node returned a non-recoverable error
10	ExecutionCancelled	Caller cancelled, or server-side cancel arrived	POST /executions/<id>/cancel, HITL rejection
11	ExecutionTimeout	Per-execution deadline exceeded	Server’s max-duration cap hit
12	ExecutionSuspended	HITL approval pending	Workflow paused on an approval node
13	Forbidden	Authenticated but no permission	Member trying admin-only mutations; agent disabled for non-admins; HTTP 403

Why 401 ≠ 403

401 Auth and 403 Forbidden mean different things and need different handling. Scripts should distinguish:

• 3 → re-authenticate (athena login or set ATHENA_API_TOKEN)
• 13 → permission problem; ask a workspace admin

Picking the right code in scripts

#!/usr/bin/env bash
set -e

athena agent run my-agent --input @./payload.json
case $? in
  0)  echo "ok" ;;
  3)  echo "need to log in"; exit 1 ;;
  6)  echo "rate-limited, retrying in 30s"; sleep 30; exec "$0" ;;
  9|11) echo "execution failed/timed out — check trace_id" ;;
  *)  echo "unknown failure"; exit 1 ;;
esac