> For the complete documentation index, see [llms.txt](https://zumo.fusion.ac/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zumo.fusion.ac/documentation/guides/errors-and-retries.md).

# Errors and retries

## Replay HTTP statuses

| `GET /replays/{id}` | Meaning           | Action                             |
| ------------------- | ----------------- | ---------------------------------- |
| `200`               | Completed         | Use body / MCPR                    |
| `404`               | Unknown           | `replayRequest`                    |
| `425`               | Queued or running | Poll status or listen WS           |
| `422`               | Prior failure     | `replayRequest` with `force: true` |
| `400`               | Bad id            | Fix UUID                           |
| `401`               | Bad key           | Fix `API-Key`                      |

Error body shape: `{ "error": "...", "replayId"?: "...", "message"?: "..." }`.

## replayRejected reasons

| Reason             | Meaning                                 |
| ------------------ | --------------------------------------- |
| `already_recorded` | Completed recording exists              |
| `in_progress`      | Same id already queued/running          |
| `invalid_id`       | UUID validation failed                  |
| `no_workers`       | No idle replay bot                      |
| `unauthorized`     | Missing provide ACL for `replayRequest` |

## replayFailed codes

`invalid_replay`, `kicked`, `aborted`, `failed`, `not_ready`, `disconnected`, `shutdown`, `worker_gone`, `worker_disconnect`

## Retry tips

* Never emit `replayRequest` before checking HTTP
* Use `force: true` only after `422` or when you intentionally re-record
* On `already_recorded`, fetch HTTP `200` / MCPR instead of forcing