# Fix a failed or stuck run



Find the failing step before retrying or changing the command.

 

## A request is rejected before a run starts



- `401`: check the API URL and bearer token.

- `409`: a reused idempotency key may have a different body, or an object is in the wrong state.

- `422`: inspect the validation response. Common causes are an unknown command, an absolute file path, or a deadline above 120 seconds.

- `429`: wait for `Retry-After`, then retry the same request and key.

- `503`: inspect the selected tool’s readiness and ask the operator to repair the missing pack or dependency.

 

## The run is failed



Read its error, native exit code and stderr. Check filenames first: a staged `src/check.py` is not the same path as `check.py`. Check the chosen command against the tool’s installed entrypoints.

 

## The run is timed\_out



Read any retained output to see how far it got. Reduce the target set or input size, lower the tool’s concurrency, or raise the deadline up to 120 seconds. Starting a new intended run requires a new idempotency key.

 

## The result is outcome\_unknown



Do not assume the command did not run. Review the run and retained evidence before repeating a side-effecting operation. Retrying a submission with the same key retrieves the existing run rather than replaying it.

 

## Cleanup is not destroyed



Ask the operator to check termination and reconciliation. Do not treat cleanup failure as ordinary successful completion.

 

## Cancel a run you no longer need



Send the cancel request, then retrieve the run until it is terminal. Partial output may still be available.

## Cancel a run

```bash
curl --fail-with-body -X POST "$SECURITY_RUN_URL/v1/tool-runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $SECURITY_RUN_API_KEY" \
  -H "Idempotency-Key: cancel-$RUN_ID"
```