Skip to main content
An old traffic signal glowing green on a wet city street at blue hour while the road just past it is blocked by barriers and an open trench, a metaphor for claude -p exiting 0 on a run that failed
8 min readBy Carlos Aragon

claude -p Exit Codes: Why a Failed Run Can Exit 0

claude -p exits 1 for most failures, but not all of them. A denied tool call exits 0 with subtype: "success", and a run stopped with SIGINT exits 0 too. So a CI step that only checks $? will pass runs that never did their job. I broke Claude Code 2.1.325 fifteen different ways this morning and recorded the exit code and the JSON result for each. Below is the full table, the surprises in it, and a 20-line gate script that catches every one of them.

What Does Each claude -p Exit Code Mean?

The headless docs promise this much: exit 0 on success, non-zero when the run fails, and 143 on SIGTERM. Here's what I actually got. The exit code was the same in text, json and stream-json for every scenario (the signal runs used text and json only). The rows in red are the ones that will fool a pipeline.

What happenedExitsubtypeis_errorNote
Clean run0successfalse
Bash command fails inside the run0successfalseClaude handled it; expected
Write denied (default mode)0successfalsepermission_denials: 1
Write denied (dontAsk)0successfalsepermission_denials: 1
SIGINT during a tool call0error_during_executiontruetext output: "Execution error"
--max-turns 1 reached1error_max_turnstruenum_turns reported as 2
--max-budget-usd reached1error_max_budget_usdtruecap overshot, answer dropped
API 400 / 429 / 500 / 5291successtrueterminal_reason: api_error
Unknown model ID1successtrueapi_error_status: 404
Not logged in1successtrue"Not logged in · Please run /login"
Unknown flag1(no JSON)-error on stderr only
Invalid --json-schema1(no JSON)-error on stderr only
SIGTERM143(no JSON)-no stdout at all

Twelve of the fifteen failures exit non-zero. Limits, API failures, auth and bad arguments all exit 1. The holes are permissions and signals, which are exactly the things that go wrong when you move a prompt from your laptop into a runner.

Why Does a Denied Tool Call Exit 0?

Because from Claude Code's point of view the run finished fine. Claude tried to use Write, the permission system said no, Claude read the denial and wrote a polite explanation. That's a completed turn. Here is the JSON result from the default-mode run, trimmed:

{
  "subtype": "success",
  "is_error": false,
  "terminal_reason": "completed",
  "num_turns": 2,
  "permission_denials": [ { "tool_name": "Write", ... } ],
  "result": "I couldn't create notes.txt. The Write call was blocked ..."
}
# process exit code: 0

In CI this is an easy way to get a green check on a job that did nothing. The prompt needs a tool you didn't allow, or a path outside the working directory, the call is denied, and Claude's apology lands in your PR comment as if it were the output. Blocks like the ones in blocking writes outside the working directory do their job, but the run around them still reports success.

The only signal is permission_denials.It's an array on the result message in json output. In stream-json you also get a system event with subtype: "permission_denied" at the moment it happens. --permission-mode dontAsk behaved identically to the default mode: same exit 0, same single denial. A Bash command that fails inside the run (I had Claude lsa path that doesn't exist) also exits 0, and that one is correct: the tool ran, Claude saw the error and carried on.

Why Do API Errors Say subtype success?

This one surprised me more. The Agent SDK docs tell you to check subtype to see whether the loop succeeded, and they list error_max_turns, error_max_budget_usd, error_during_execution and error_max_structured_output_retries. API errors aren't in that list, and in practice they don't get their own subtype.

I pointed ANTHROPIC_BASE_URL at four tiny local stubs that answered every request with 400, 429, 500 and 529, with CLAUDE_CODE_MAX_RETRIES=2 so each run gave up in under 4 seconds. Every one of them, plus an unknown model ID and a machine with no login, came back as:

"subtype": "success", "is_error": true, "terminal_reason": "api_error"

The process did exit 1, so $? catches these. But if your wrapper parses the JSON and branches on subtype == "success", which is what the docs example does, an overloaded API looks like a finished task. Check is_error first, always. The unknown model also carries api_error_status: 404, which is handy for telling a typo from an outage.

Each stub got exactly 3 requests per run, which is 1 + 2 retries, including the 400. The third request for the 400 carried a smaller thinkingblock, so Claude Code seems to retry some 400s with an adjusted body. With the default of 10 retries and backoff up to 32 seconds, a real 529 storm will hold a CI job for minutes before it exits 1. If you'd rather wait it out on purpose, CLAUDE_CODE_RETRY_WATCHDOG=1 retries 429 and 529 indefinitely. I wrote about the rate-limit side of this in Claude API 429 rate limits.

What Happens When You Stop claude -p With a Signal?

I started a run that had to sit through a 25-second Bash command, then signaled it 9 seconds in (and again 1 second in, during the first model request). The results were the same both times:

  • SIGTERM: exit 143 within 0.4 s, nothing on stdout, nothing on stderr, no JSON. That matches the docs.
  • SIGINT: exit 0. Text output printed Execution error. The JSON result said subtype: "error_during_execution", is_error: true, terminal_reason: "aborted_tools", and no result.

So the JSON is honest about the interrupt and the exit code isn't. Where does SIGINT come from in real life? Ctrl-C, process supervisors that use it for a graceful stop, and GitHub Actions. When you cancel a run, GitHub's runner sends SIGINT to the step's entry process first, then SIGTERM 7.5 seconds later. In a normal run: step the entry process is bash, not Claude, but if you exec claude or call it from a Node action, Claude is the one that gets the SIGINT. A claude -p ... && git push line then has a 7.5-second window to push half-done work.

For timeouts, send SIGTERM. GNU timeoutdoes by default. If you can't control the signal, the JSON gate below catches the SIGINT case because is_error is true.

Where Do claude -p Errors Go in Text Mode?

To stdout. Error: Reached max turns (1), Error: Exceeded USD budget (0.000001), API Error: 529 ... and Not logged in · Please run /login all came out on stdout, with stderr empty. Only startup problems, an unknown flag or an invalid --json-schema, wrote to stderr and left stdout empty.

That matters for the most common headless pattern there is: claude -p "..." > release-notes.md. If the run fails, the error string becomes your release notes. The exit code stops the next step only if you're running with set -e or checking $?, and even then the file is already written. Use JSON output for anything a script consumes and extract .result only after the gate passes.

Do --max-turns and --max-budget-usd Stop Exactly at the Limit?

--max-turns 1 on a task that needed two Bash calls stopped after the first tool call and exited 1 with error_max_turns. The result reported num_turns: 2, because the count includes the turn that was cut off. Don't alert on num_turns > max_turns; alert on the subtype.

--max-budget-usd is a check after the fact, not a hard stop. With a cap of $0.000001, Haiku 5.5 wrote a full 200-word story, the run spent $0.000215, and then it exited 1 with error_max_budget_usd. The story showed up in the stream-json assistant events, but the final JSON had no resultfield at all. So you pay for the answer and don't get it. The CLI reference warns that spend can pass the cap. Set the budget at about 2x your normal run cost so it only trips on runaway loops. If you need to keep partial work, read stream-json instead. My Claude Code GitHub Actions cost breakdown has real per-run numbers to size it from.

How Do You Fail a CI Job When claude -p Fails?

Check four things: the JSON exists, is_error is false, subtype is success, and permission_denialsis empty. Then fall back to the exit code. Here's the gate I wrote and tested against every result above. It needs jq:

#!/usr/bin/env bash
# claude -p "..." --output-format json > result.json; ./gate.sh result.json $?
set -uo pipefail
f="$1"; rc="${2:-0}"
if [ ! -s "$f" ]; then
  echo "claude produced no JSON (exit $rc)" >&2; exit "${rc/#0/1}"
fi
read -r subtype is_error denials reason < <(tail -n 1 "$f" | jq -r \
  '[.subtype, .is_error, (.permission_denials|length), (.terminal_reason // "none")] | @tsv')
if [ "$is_error" = "true" ] || [ "$subtype" != "success" ]; then
  echo "claude run failed: subtype=$subtype terminal_reason=$reason" >&2; exit 1
fi
if [ "$denials" -gt 0 ]; then
  echo "claude finished but $denials tool call(s) were denied:" >&2
  tail -n 1 "$f" | jq -r '.permission_denials[] | "  - \(.tool_name)"' >&2; exit 2
fi
if [ "$rc" -ne 0 ]; then echo "claude exited $rc with a success result" >&2; exit "$rc"; fi
echo "ok"

And in the workflow step:

claude -p "Update CHANGELOG.md for this release" \
  --output-format json --max-turns 20 > result.json
./gate.sh result.json $? || exit $?
jq -r .result result.json > summary.md

I ran it against the saved JSON from every scenario above. It passed the clean run and the failed-Bash run, exited 2 on both permission denials (listing Write), and exited 1 on max turns, budget, unknown model, no login, every API error and the invalid schema. The SIGINT result trips it on is_error. Exit 2 for denials is deliberate. Sometimes a denial is fine, and a separate code lets a job decide that for itself.

Two more settings make the gate's job easier. --bare or --setting-sources ""stop a teammate's hooks or MCP servers from changing the run (I measured what that does to tokens in claude -p bare mode token overhead). And an explicit --allowedTools list turns surprise denials into the rare case they should be.

claude -p Exit Code FAQ

What exit code does claude -p return when it fails?

Usually 1: max turns, max budget, API errors, an unknown model, a missing login, unknown flags and an invalid --json-schema all exited 1 in my tests on Claude Code 2.1.325. SIGTERM exits 143. Denied tool calls and SIGINT during a tool call exited 0.

Does claude -p exit non-zero when a tool is denied?

No. In both default and dontAsk permission modes a denied Write call ended with exit 0, subtype success and is_error false. The only signal is the permission_denials array in the JSON result, or permission_denied events in stream-json.

Why does claude -p say subtype success when the API call failed?

For API errors, an unknown model and a missing login, the result message keeps subtype success and sets is_error true with terminal_reason api_error. The process still exits 1. Check is_error, not subtype alone.

Where does claude -p print errors in text mode?

Run errors such as 'Error: Reached max turns (1)' or 'API Error: 529 ...' go to stdout, with stderr empty. Only startup errors like an unknown flag or an invalid --json-schema go to stderr. If you redirect text output to a file, the error message ends up in that file.

Does --max-budget-usd stop claude -p exactly at the cap?

No. With a $0.000001 cap the run made one full model call, spent $0.000215, then exited 1 with error_max_budget_usd. The generated text appeared in the stream-json events but was not in the final result field. The docs say to leave headroom.

How I Tested

November 15, 2026, on a Mac mini in Allen, TX, with Claude Code 2.1.325 signed in to a Max plan. Every run used claude-haiku-5-5 at --effort low, --setting-sources "", an empty --mcp-config with --strict-mcp-config, and --no-session-persistence, started from Python with a clean environment (HOME, PATH, USER only) and stdin closed. The matrix was 14 scenarios x 3 output formats = 42 runs. Then I added signal runs and repeat API-error runs, about 60 runs in total. The no-login case used an empty CLAUDE_CONFIG_DIR and HOME. The API errors came from local Python stubs, so no real outage was involved. Client-side cost estimates for the whole set came to under one cent.

If you're deciding where Claude Code fits next to your other automation, start with Claude Code vs n8n.

Running Claude Code Unattended?

I build agent pipelines that run every day without anyone watching them. If yours keeps passing jobs that did nothing, send me the workflow file and I'll show you where it's leaking.

Related Posts