CLI errors

Staplehire CLI failures print one structured JSON object to stderr and exit with a stable, non-zero code, so humans, scripts, and agents can recover predictably. Branch on the exit code first, then on error.code.

{
  "error": {
    "name": "ValidationError",
    "code": "candidate_email_invalid",
    "message": "Invalid email address",
    "hint": "Use a valid email format",
    "field": "email",
    "requestId": "req_…",
    "status": 400
  }
}

Never grep error.message — the wording can change. Parse error.code (stable) and read error.hint / error.field to fix the request. Log error.requestId when contacting support.

First step when a command fails

staplehire doctor -q

Then capture the command’s stderr and inspect the error:

staplehire candidates create <roleId> --email not-an-email --stage Sourced 2> error.json
jq '.error' error.json

Exit codes

Code	HTTP	Meaning	Typical fix
`0`	—	Success	Parse stdout
`1`	other	Generic / internal	Retry; inspect `error.requestId` and escalate
`2`	401	Authentication	Run `staplehire login` or set `STAPLEHIRE_KEY`
`3`	400	Validation	Fix the field named in `error.field` / `error.hint`
`4`	404	Not found	Re-list the parent resource and use a real ID
`5`	409	Conflict	Reuse the existing resource or change unique fields
`6`	403	Permission	Check the key’s organization and scope
`7`	502	Upstream	Retry with backoff
`8`	—	CLI usage / bad args	Run `staplehire <command> --help` or `staplehire commands`
`9`	—	`jobs poll` timeout	Re-run `jobs poll` with a higher `--timeout`, or use `jobs get`

Common `error.code` values

Code	Resolution
`candidate_email_invalid`	Fix the email syntax
`candidate_already_exists`	The email exists on this role — find and move the existing candidate
`stage_name_already_exists`	Reuse the stage or pick a new name
`stage_not_found`	Run `staplehire stages list <roleId>`
`role_not_found`	Confirm the role created successfully (`roles list`)
`interview_design_required`	Run `designs create` before sending an interview
`job_failed`	Read `error.message`; fix inputs or retry with `--force`
`api_key_invalid`	Create a new key — see Authentication
`api_key_revoked`	Issue a new key in Settings → Developers
`org_not_provisioned`	Contact support

Error types

AuthenticationError (exit 2)

The CLI could not resolve or validate an API key.

staplehire login          # local
# or, for agents and CI:
export STAPLEHIRE_KEY=sh_live_xxx
staplehire doctor -q

ValidationError (exit 3)

A required value is missing or invalid. Fix the field named by .error.field, then rerun.

NotFoundError (exit 4)

A role, candidate, design, stage, or job ID does not exist or isn’t visible to your organization.

staplehire roles list
staplehire candidates list --role-id <roleId>
staplehire designs list <roleId>
staplehire jobs get <jobId>

ConflictError (exit 5)

A resource already exists — commonly a duplicate candidate email on the same role.

staplehire candidates list --role-id <roleId> --email alex@example.com

Poll timeout (exit 9)

jobs poll stopped waiting. It does not mean the job failed.

staplehire jobs poll <jobId> --interval 5000 --timeout 300000
staplehire jobs get <jobId>

Capture and branch in a shell script

if ! out=$(staplehire candidates create "$ROLE_ID" --email "$EMAIL" --stage Sourced 2> err.json); then
  code=$?
  err=$(jq -r '.error.code // "unknown"' err.json)
  echo "failed (exit $code): $err" >&2
  case "$err" in
    candidate_already_exists) echo "→ move the existing candidate instead" >&2 ;;
    stage_not_found)          staplehire stages list "$ROLE_ID" ;;
  esac
  exit "$code"
fi
echo "$out" | jq -r '.candidate.id'

Agent loop rule: if the same error.code repeats with the same payload, change the inputs or stop — do not retry blindly.

FAQ

Where does error JSON print?

To stderr. Successful data prints to stdout, so you can pipe stdout cleanly while still capturing errors separately.

What should I send to support?

The error.requestId, the exact command, and the timestamp.

Why did `jobs poll` exit with code 9?

The --timeout elapsed. The job may still be running — inspect it with jobs get or poll again.

Related: Authentication · Poll jobs · Command reference

Get started

Workflows

Automation

Reference

First step when a command fails

Exit codes

Common `error.code` values

Error types

AuthenticationError (exit 2)

ValidationError (exit 3)

NotFoundError (exit 4)

ConflictError (exit 5)

Poll timeout (exit 9)

Capture and branch in a shell script

FAQ

​First step when a command fails

​Exit codes

​Common error.code values

​Error types

​AuthenticationError (exit 2)

​ValidationError (exit 3)

​NotFoundError (exit 4)

​ConflictError (exit 5)

​Poll timeout (exit 9)

​Capture and branch in a shell script

​FAQ

First step when a command fails

Exit codes

Common `error.code` values

Error types

AuthenticationError (exit 2)

ValidationError (exit 3)

NotFoundError (exit 4)

ConflictError (exit 5)

Poll timeout (exit 9)

Capture and branch in a shell script

FAQ