> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/cli-reference/idempotency.md).

# Mutation retries and idempotency

Agents must distinguish a rejected mutation from a mutation whose result is unknown.

## Automatic retry contract

The shared CLI client automatically retries authenticated `GET` requests on HTTP 429, 503, and 504 responses, honoring `Retry-After` when present. It attempts token refresh once after a 401 response.

`POST`, `PUT`, `PATCH`, and `DELETE` requests are sent once. The CLI does not retry transient mutation responses because the server may have applied the change before the connection failed.

## Agent workflow

1. Read current state and capture UUIDs, canonical names, versions, or status.
2. Send one mutation.
3. If the command succeeds, inspect the returned state and perform the smallest verification read when needed.
4. If validation, permission, or conflict is returned, correct that state rather than retrying unchanged.
5. If timeout, connection failure, 503, or 504 occurs after a mutation was sent, treat the result as unknown. Read current state before deciding whether to retry.

## Mutation families

| Mutation                               | Verification before retry                                                                                       |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Create Agent or component              | List or show by canonical `namespace/slug`; do not create again if it exists                                    |
| Publish or release version             | Read version history and review status                                                                          |
| Update visibility, role, or settings   | Read the specific resource and compare the desired field                                                        |
| Approve or reject a request            | Read request status by UUID                                                                                     |
| Archive, restore, revoke, or delete    | Show the resource or confirm not-found where deletion is expected                                               |
| Install or pull                        | Inspect returned files and run `scan` for the target harness                                                    |
| Bulk submit                            | Re-run only after reviewing per-entry results; existing identities return conflicts and are reported as skipped |
| Server upgrade, rollback, or migration | Read service version, migration validation, and destination state before any retry                              |

## Conflict behavior

A conflict is deterministic information, not a transient failure. Common decisions include:

* Use `qualified_name` when a bare name is ambiguous.
* Use update only when the user requested an in-place change.
* Use release or version publish when the user requested a new version.
* Treat an already-created bulk component as skipped after verifying its identity.
* Do not bypass edit locks or ownership conflicts.

The `observal api` escape hatch follows the same retry rules because it uses the shared authenticated client.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.observal.io/cli-reference/idempotency.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.