Skip to main content

Documentation Index

Fetch the complete documentation index at: https://staplehire.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Staplehire CLI failures return structured JSON on stderr and stable exit codes so humans, scripts, and agents can recover predictably. 
{
  "error": {
    "name": "ValidationError",
    "code": "candidate_email_invalid",
    "message": "Invalid email address",
    "hint": "Use a valid email format",
    "field": "email",
    "requestId": "req_...",
    "status": 400
  }
}

​
Quickstart

Run doctor first when a command fails unexpectedly. 
staplehire doctor -q
Then inspect the command-specific error JSON on stderr. 
staplehire candidates create <roleId> --email not-an-email 2> error.json
jq '.error' error.json

​
Exit codes

CodeMeaningTypical fix
1Generic or internal errorRetry or inspect requestId
2Authentication, usually 401Run staplehire login or set STAPLEHIRE_KEY
3Validation, usually 400Fix the flagged field or missing argument
4Not found, usually 404List resources and use a real ID
5Conflict, usually 409Reuse the existing resource or change unique fields
6Permission, usually 403Check key organization and user permissions
7Upstream, usually 502Retry later or contact support with requestId
8CLI usage or bad argsRun staplehire <command> --help or staplehire commands
9Poll timeoutRe-run jobs poll with a longer timeout

​
AuthenticationError

The CLI could not resolve or validate an API key. 
staplehire login
staplehire whoami
For CI and agents: 
export STAPLEHIRE_KEY=sh_live_xxx
staplehire doctor -q

​
ValidationError

A required value is missing or invalid. 
{
  "error": {
    "name": "ValidationError",
    "code": "candidate_email_invalid",
    "field": "email",
    "message": "Invalid email address"
  }
}
Fix the field named by .error.field, then rerun the command.

​
NotFoundError

A role, candidate, design, stage, or job ID does not exist or is not visible to the current organization. 
staplehire roles list
staplehire candidates list --role-id <roleId>
staplehire designs list <roleId>
staplehire jobs get <jobId>

​
ConflictError

A resource already exists, commonly a duplicate candidate email on the same role. 
staplehire candidates list --role-id <roleId> --email alex@company.com

​
Poll timeout

Exit code 9 means jobs poll stopped waiting. It does not necessarily mean the job failed. 
staplehire jobs poll <jobId> --interval 5000 --timeout 300000
staplehire jobs get <jobId>

​
FAQ

​
Where does error JSON print?

Errors print to stderr. Successful data prints to stdout.

​
What should I send to support?

Send .error.requestId, the command, and the timestamp.

​
Why did jobs poll exit with code 9?

The timeout elapsed. The job may still be running, so inspect it with jobs get or poll again. Related: Authenticate the Staplehire CLI · Poll Staplehire CLI jobs · Command reference