Browse the docs ▾

Agent guides

Revisions, errors and recovery

Most failures tell you exactly what to do. Read the code, follow it, and don't retry blindly.

Errors and limits lists the common codes. This page explains what to do next.

Revisions

Every design read and write gives a revision. Send it as base_revision with your next write. Items have their own revision, from get_item. If anyone changed the design or item since, you get REVISION_CONFLICT. This is normal, particularly if the owner has the builder open.

1

Read the page or item again.

2

Check that your change still makes sense. The owner may have done something similar, or moved the node.

3

Rework the change on the new revision, and send it.
Don't simply swap in the new revision and resend a batch you haven't re-read.

Choosing what to do

REVISION_CONFLICT

Read again and redo the change.

REF_NOT_FOUND

Read again, as the node may have moved. The error can list candidates.

UNKNOWN_FIELD, UNKNOWN_TOKEN

Read the allowed keys, or add the field first.

INVALID_OP, INVALID_VALUE, PROPERTY_NOT_ALLOWED

Fix the op. The message names it. Nothing in the batch was applied.

VALIDATION_FAILED, SLUG_TAKEN, CODE_TAKEN

Change the value.

PUBLISH_TOKEN_INVALID

Preview again. The token was used, expired, or the change differs.

BUSY

Wait retry_after seconds and send the same request.

RATE_LIMITED

Wait and retry. Slow down: 30 changes a minute at most, so use larger batches.

INTERNAL

Try once more. If it continues, tell the owner, and don't assume the change happened.

SCOPE_MISSING, ROLE_FORBIDDEN, ORG_NOT_GRANTED

Don't work around these. Tell the owner what's needed.

AGENTS_PAUSED

Stop and tell the owner.

A plan refusal

Give the owner the link in the error. Plans are chosen in the browser.

Safe retries

If a call times out, you don't know whether it worked.

create_item, upload_image

Send an idempotency_key. The same key within 24 hours returns the first result.

apply_site_ops

It's all or none. Read the site: if the revision changed and your change is there, it worked.

Imports

Give every row an idempotency_key. Sending the import again within a day of the first returns what was made and tries the rest. After that, or without keys, a row may be refused as taken, or a product with no code may be made again.

Publishing

After a timeout, check with get_site or get_item before you preview again.
Long imports and publishes run in the background. Poll get_import with limit: 0 until they finish, then read only: "failed".

Undoing your work

A design batch

undo_site_change with its action_id. If you get UNDO_CONFLICT, later changes are in the way, so undo those first.

An older design change

You can't list earlier action_ids, so keep each one as you go. The owner can step back through the builder's history.

An item edit

update_item returns the previous values. Send them back.

A live save

Most saves return the previous values; preview and save those to put them back. save_custom_type doesn't, so read the type with list_custom_types first. Order steps can't be undone by an app.

Published items

preview_item_publish with action: "unpublish", then unpublish_item.

Archived products

preview_product_archive with action: "restore" restores those an app archived.

A published site

There's no publish rollback tool. Correct the draft and publish again, or ask the owner to use the builder's history.

When you've made a mistake

Tell the owner plainly what happened, what it changed and how you put it right. Settings › AI apps shows them every change anyway. Don't hide a failed step or a warning, and don't mark something as done on the strength of an unverified retry.

‹ Previous

Draft or live

A conflict

apply_site_ops { "base_revision": "7d95…" }

→ { "error": {
    "code": "REVISION_CONFLICT",
    "current_revision": "9c1e…" } }

get_page_outline
→ "revision": "9c1e…"
  The headline was changed by the owner.

You: You've just changed the headline
     in the builder. Should I keep yours?

A safe retry

create_item {
  "org_id": 1042,
  "content_type_id": 402,
  "title": "Spring menu",
  "idempotency_key": "spring-menu-2026"
}

(timeout)

create_item { … the same key … }
→ the same item, not a second one

‹ Previous

Draft or live