Usage Exit Codes and Logging

Exit codes & logging

Part of the Usage reference. · ← Previous: Files & locations

Exit codes

Since v0.1.37-2, every failure is classified into an error type, and two types get their own exit code so scripts can react without parsing messages:

Exit code	Meaning
0	Success.
75	rate_limited: Steam (or another server) is throttling requests. Wait before retrying. (EX_TEMPFAIL)
77	auth_required: no usable session. Run aurelia login. (EX_NOPERM)
1	Any other failure.

Clap's own argument errors (an unknown flag, a missing value) keep clap's usual exit code 2.

Error output

Without --json, the error goes to stderr as Error: <message>, followed by the cause chain.

With --json, the error is a single line on stdout (so it stays valid inside NDJSON streams such as install):

{"error":"could not restore the stored session: …","type":"rate_limited","hint":"Steam is throttling this client; pause before retrying","retry_after_seconds":20}

Field	Present	Meaning
error	always	The full message, including its causes.
type	always	The error type (see below).
hint	some types	A short suggestion for what to do.
retry_after_seconds	when known	How long the server asked to wait (from Retry-After or GitHub's rate-limit reset).

type	Meaning	hint
invalid_input	A bad argument, e.g. an invalid country code, a non-SteamID64 number, or a vanity URL where a SteamID is needed.
not_found	The app, item or user doesn't exist, or isn't in your library.
rate_limited	Steam or a web server is throttling requests (HTTP 429, Steam's rate-limit results, or GitHub's API limit).	Steam is throttling this client; pause before retrying
access_denied	Steam refused the request.
privacy_restricted	The profile or list is private or friends-only, e.g. a non-friend's wishlist.	the profile or list is private or friends-only
network_timeout	A timeout, a refused connection, or Steam reporting it is busy or unavailable.	check connectivity and retry
source_changed	Steam changed the shape of a response.	Steam changed a response shape; update Aurelia
auth_required	Not logged in, invalid credentials, or the stored session could not be restored.	run aurelia login
unknown	Anything not classified above.

When the session daemon could not restore the stored session, a command that needs a session reports why (for example rate_limited with its retry_after_seconds) instead of a plain "not logged in".

Logging

Increase verbosity with -v/-vv/-vvv (see Global behavior), or with the RUST_LOG environment variable, e.g.:

RUST_LOG=debug aurelia play 1245620

Retries of rate-limited or failed web requests are logged as warnings, so they show up without -v.