Exit codes - Reqbook

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

rqb validate api-docs/ || exit 1

Inspect the exit code of a single endpoint test

rqb exec api-docs/apis/health/get-health.md --env=staging
echo "Exit: $?"

Distinguish a network failure from a response mismatch

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

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

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 }}

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.

​Overview

​When each code fires

​CI usage examples

​GitHub Actions example

Overview

When each code fires

CI usage examples

GitHub Actions example