# Rental lifecycle and retries

Track readiness, stop deliberately, and recover from ambiguous requests without duplicate rentals.

Track the rental ID returned by a reservation. The normal path is:

```text
RESERVED → STARTING → RUNNING → STOPPING → STOPPED
```

Failures and interruptions can end work without following every normal transition. Treat the server's state and reason as authoritative, not a timer in your client.

## What each stage means

- **RESERVED:** the reservation has been accepted and budget held. This is not verified execution readiness.
- **STARTING:** the workload is being prepared. Model loading and readiness checks can take time.
- **RUNNING:** readiness has been verified and runtime metering has started.
- **STOPPING:** shutdown has been requested or triggered. Continue observing until a terminal state.
- **STOPPED:** execution has ended. Any result-retrieval access is read-only and time-limited.
- **FAILED:** inspect the reason. An unready start has no runtime charge; use the receipt to inspect the actual outcome of a rental that had already run.

## Make reservation retries deliberate

Generate and persist an `Idempotency-Key` UUID before `POST /api/v1/jobs`. Keep the exact request body with it. On a network timeout, retry that same reservation request with the same key, or inspect your existing rentals first. Do not generate a new key merely because the response was lost.

A reused key with a different request is not a new operation; expect an idempotency conflict. A fresh quote is also not a replay of the old quote: every quote call creates a new record.

MCP `create_rental` quotes and reserves in one tool call. Save the returned `idempotency_key`. If a previous attempt might have succeeded, use `list_rentals` before retrying: its new quote step may fail because the machine is already reserved even though the earlier reservation succeeded.

## End or extend the work

Save results, then request `POST /api/v1/jobs/{id}/stop` with a reason and a stable idempotency key. Repeated stopping is harmless; it is not permission to ignore the response state.

An extension explicitly adds funded budget and a new duration limit using expected job and budget versions. A stale-version response requires a fresh read, not a blind overwrite. Increasing a budget is a new spending decision and needs the operator's authorization.

Finally, read the [receipt](https://docs.amplerun.com/billing/budgets-and-receipts.md). A submitted stop request, browser tab closure, or disconnected client is not by itself evidence that work has ended.

---
Last reviewed: 2026-10-19.
Canonical: https://docs.amplerun.com/renting/lifecycle/