# What do the DunSocial CLI exit codes mean?

> 0 is success, 1 usage, 2 auth, 3 forbidden or missing scope, 4 validation, 5 not found, 6 rate limited & 7 network. Retry 6 & 7 with backoff; fix 2, 3 & 4 before trying again.

Updated: 2026-10-05.

## Why exit codes matter

In a script or CI job, the exit code is how your pipeline learns what happened. A single non-zero code isn't enough: a rate limit should be retried, but a missing scope never will succeed.

## The codes

| Code | Meaning | What to do |
|------|---------|------------|
| 0 | Ok | Continue |
| 1 | Usage or unknown command | Fix the command |
| 2 | Auth | Sign in or fix the token |
| 3 | Forbidden or missing scope | Grant the scope or check the workspace |
| 4 | Validation | Fix the input, such as length or metadata |
| 5 | Not found | Check the id |
| 6 | Rate limited | Wait & retry |
| 7 | Network | Retry, then check connectivity |

## Retry the right ones

Codes 6 & 7 are transient. Retry with exponential backoff, a few times at most.

Codes 2, 3 & 4 won't fix themselves. Retrying only burns time & can trip rate limits. Fail the job & surface the message.

## A small shell example

```bash
dun posts schedule --text "Release shipped" --accounts "$ACCOUNT" --in 5m --json
code=$?

case $code in
  0) echo "scheduled" ;;
  6|7) echo "transient, retry later" ; exit 1 ;;
  *) echo "permanent failure ($code)" ; exit 1 ;;
esac
```

Treat anything not explicitly transient as permanent. That's the safer default.

DunSocial's codes are stable across commands, so one `case` block can wrap every call.

## Matching the error JSON

With `--json`, the same failure also appears on stdout with an `error.code` such as `validation`. The exit code is the quick signal & the JSON gives the detail.

If you log failures, log the message but never the token.

DunSocial prints both, so you can log the JSON & branch on the code.

## A common cause for each

- 2: a revoked or expired token, or `DUN_TOKEN` not set in the job
- 3: a personal access token missing a scope such as `posts:schedule`, or the wrong workspace id
- 4: a post that's too long, or Instagram without a `format`
- 6: too many requests, or the X monthly posting cap

DunSocial's token scopes are listed in the CLI's authentication docs, so check there first when you see a 3.

## Check status first

`dun auth status --json` is a cheap first step in any pipeline. If it fails with a 2, you know the problem is auth before you attempt to post anything.

DunSocial's status command makes no changes, so it's safe to run at the start of every job.

## Related guides

- [How to script the DunSocial CLI with JSON output](https://www.dunsocial.com/hub/dunsocial-cli-guides/how-to-script-the-dunsocial-cli-with-json-output.md)
- [How to run the DunSocial CLI in GitHub Actions](https://www.dunsocial.com/hub/dunsocial-cli-guides/how-to-run-the-dunsocial-cli-in-github-actions.md)
- [What do DunSocial API error codes mean?](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/what-do-dunsocial-api-error-codes-mean.md)
- [What happens if a scheduled post fails?](https://www.dunsocial.com/hub/social-media-scheduler/what-happens-if-a-scheduled-post-fails.md)

## About this document

This is the Markdown representation of https://www.dunsocial.com/hub/dunsocial-cli-guides/what-do-the-dunsocial-cli-exit-codes-mean. The HTML version of the same page is at the same URL. You can also request Markdown from any page by sending `Accept: text/markdown`.

Machine-readable summary of the whole site: https://www.dunsocial.com/llms.txt

## Company

- Product: DunSocial, https://www.dunsocial.com
- Legal entity: THISUX PRIVATE LIMITED, Chennai, Tamil Nadu, India
- Support: support@dunsocial.com
- Open the app: https://app.dunsocial.com/login