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
rqb exec api-docs/apis/health/get-health.md --env=staging
echo "Exit: $?"
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
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.
