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

# Retries and recovery

> Recover from unknown responses, stale attempts, blockers, handoffs, failed checks, rework, and cancellation.

Choose recovery based on what Kiwi confirmed. A known validation, authority, missing-resource, or stale-command rejection means Kiwi rejected that request. A lost response or server error can occur after a run commit, so do not treat every HTTP error as proof that nothing happened.

## Unknown outcome or definitive rejection

| What you observed | What to do |
| - | - |
| Connection closed, timeout, or client ended before the response; no definitive service error | Retry the identical command with the same command\_id (or MCP commandId), same payload, expected version, attempt, and declared harness/session. Kiwi returns the stored receipt if it recorded the command. |
| 400 validation error, 401 or 403 authority error, or 404 resource error | The request was rejected. Fix the input or access, read current state, then use a new command ID for the next valid command. |
| 409 stale version, stale attempt, invalid transition, or changed replay content | Read the current run and attempt. Preserve the current attempt ID when it remains active; create a new command ID for the updated request. Do not reuse the old command ID with changed content. |
| 500 or another 5xx, including a timeout returned by a proxy | Unless the response identifies a known application rejection, treat the outcome as uncertain. For a run command or checker report, retry the identical command ID and body. |
| 503 integration dependency unavailable | Do not assume the operation completed. Check its current status in Kiwi before trying again. |

Every run state mutation requires a positive current expected\_run\_version. Do not reuse a version from before another action. See the [Integration API reference](https://docs.kiwiflow.io/api-reference.md) for the supported external request shapes.

## Attempt IDs

When a ready node has no currentAttemptId, generate a new UUID for the first attempt. Use the currentAttemptId returned by the server for subsequent mutations to that attempt. Do not invent an attempt ID from a null field.

For a manually reported resumable blocker, only the same principal, performer, and session may resume the blocked attempt; call start\_step with that same attempt ID. A new agent session must not impersonate the old session to resume it.

A handoff\_step call ends the current performer attempt and queues the step under a new ID reserved for the run's responsible human. The responsible human starts that queued attempt. An unrelated agent cannot claim it.

## Checks and candidate changes

Before reporting CI evidence, read `GET /v1/runs/{runId}/checks`. Use its current runVersion, accepted plan revision, candidate reference, implementation attempt, and verification attempt. If Verify is ready and verificationAttemptId is null, generate one UUID for the first checker report; then use the returned current attempt on later reports.

Each check binds to the current accepted Plan, candidate, Implement attempt, and Verify attempt. A pass is the only status that can satisfy the gate. fail fails Verify; blocked and not-applicable do not satisfy it. Failed or blocked check outcomes require authorized rework; they cannot be resumed as a manually reported blocker.

Rework preserves attempt history. It can keep the current accepted Plan or explicitly revise it. Revising Plan increments the Plan revision and returns to Plan. Rework at Implement invalidates the current candidate and all dependent verification and review evidence. Reports for the previous candidate remain visible but cannot pass the new gate. Rerun checks and review against the new candidate.

## Credential outcomes

If MCP or checker credential issuance has an unresolved result, inspect its nonsecret status in the Kiwi app before creating another credential. An issuance replay does not reveal an already-issued secret. If the secret is confirmed lost, use the app to revoke that credential and issue a replacement.

If Kiwi shows that revocation is pending, use the available retry action in the app and check its status there.

## Rework, handoff, and cancellation

An authorized human can request rework through the app. The request needs a reason and may set revise\_plan. The designated owner decides rework on a submitted Plan; other rework follows the workflow's authorized role. A responsible human or project Admin can cancel with a reason. Cancellation prevents future Kiwi run transitions but does not stop external agents, jobs, or systems.

Use [Manual participation](https://docs.kiwiflow.io/participation.md) for human roles and structured step outputs, and [Runs and history](https://docs.kiwiflow.io/runs-and-history.md) to inspect current attempts and prior events.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.