> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markapidown.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Exit codes

> Reqbook returns stable exit codes so CI pipelines can act on pass, failure, invalid spec, or secret detection independently.

## Overview

Reqbook uses six exit codes. All are stable across versions you can reliably test for them in CI scripts without worrying about changes between releases.

| Code | Name            | When it occurs                                                                                         | CLI commands that can return it                              |
| ---- | --------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| `0`  | Passed          | All checks passed; response matched the expected response.                                             | All commands.                                                |
| `1`  | Test failed     | Response did not match the expected response.                                                          | `exec`, `flow`, `doctor`                                     |
| `2`  | Invalid spec    | Frontmatter error, missing required section, unresolved variable, or environment mismatch.             | `exec`, `flow`, `validate`                                   |
| `3`  | Engine error    | Request build failed or unsupported protocol.                                                          | `exec`, `flow`, `init`, `index`, `import`, `skills`, `serve` |
| `4`  | Network error   | DNS failure, unreachable host, or timeout exhausted.                                                   | `exec`, `flow`                                               |
| `5`  | Secret detected | A secret pattern was found in a versioned markdown file. Exits immediately before any network request. | `exec`, `flow`, `validate`                                   |

***

## When each code fires

**Exit code 1 Test failed**
The request was sent successfully and a response was received, but one or more assertions in `## Expected response` did not match. Check the diff output to see which fields diverged.

**Exit code 2 Invalid spec**
Reqbook could not build a valid request from the spec. This covers malformed frontmatter, missing required sections, unresolved `{{variable}}` references, and `--env` values that have no matching heading in `env.md`. The error message includes the file path, line number when available, and a suggested fix.

**Exit code 3 Engine error**
An internal failure prevented Reqbook from building the HTTP request. Common causes: unsupported protocol value in frontmatter, filesystem error reading a file, or a corrupted binary. Check the `--verbose` output for details.

**Exit code 4 Network error**
The request was built and sent but no response was received. Covers DNS resolution failure, connection refused, and timeout expiry across all retry attempts.

**Exit code 5 Secret detected**
Reqbook found a pattern matching a secret (JWT token, hex API key, `sk_` prefixed key, etc.) in a markdown/config file. The process exits immediately no request is sent, no spec is executed. Move the value to `.env.local` or a `RQB_*` environment variable.

***

## CI usage examples

**Fail CI on any invalid spec**

```bash theme={null}
rqb validate api-docs/ || exit 1
```

**Inspect the exit code of a single endpoint test**

```bash theme={null}
rqb exec api-docs/apis/health/get-health.md --env=staging
echo "Exit: $?"
```

**Distinguish a network failure from a response mismatch**

```bash theme={null}
rqb exec api-docs/apis/users/get-user-by-id.md --env=staging --var id=usr_123
CODE=$?
if [ $CODE -eq 1 ]; then echo "Response mismatch check spec or API behavior"; fi
if [ $CODE -eq 4 ]; then echo "Network unreachable check VPN or service health"; fi
```

**Full case statement**

```bash theme={null}
rqb exec api-docs/apis/users/get-user.md --env=staging
CODE=$?
case $CODE in
 0) echo "Passed" ;;
 1) echo "Response mismatch check the spec or API behavior" ; exit 1 ;;
 2) echo "Invalid spec run rqb validate to see errors" ; exit 1 ;;
 4) echo "Network error check VPN, service health, or BASE_URL" ; exit 1 ;;
 5) echo "Secret committed to spec file fix before merging" ; exit 1 ;;
 *) echo "Unexpected error (code $CODE)" ; exit 1 ;;
esac
```

***

## GitHub Actions example

```yaml filename=".github/workflows/api-tests.yml" theme={null}
name: API spec tests

on:
 push:
 branches: [main]
 pull_request:
 paths:
 - 'api-docs/**'

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Install Reqbook
 run: curl -fsSL https://markapidown.net/install.sh | sh

 - name: Validate specs
 run: rqb validate api-docs/

 - name: Run health check
 run: rqb exec api-docs/apis/health/get-health.md --env=staging
 env:
 RQB_BASE_URL: https://staging.example.com
 RQB_AUTH_TOKEN: ${{ secrets.STAGING_TOKEN }}
```

<Tip>
  Use `RQB_*` environment variables to pass secrets into CI. They map automatically to camel-case variable names `RQB_AUTH_TOKEN` becomes `{{authToken}}` in your specs.
</Tip>