Engine response

409 Conflict: catalog changed

, imagine.io ·

What it means. The catalog version your page loaded is older than the one on the server, usually because someone published a new version of the system while the shopper was configuring.

BrowserSDK, iframe oryour own pageone mutation+ the stateTHE ENGINE1Check the catalog version2Apply the mutation3Matching rules4Constraints, then price200 appliedresolved state + price409 catalog changedrefetch and retry422 rejectedreason, previous state keptstateless: every request carries the full current state BrowserSDK, iframe or your own pageone mutation + the stateTHE ENGINE1Check the catalog version2Apply the mutation3Matching rules4Constraints, then priceone of three answers200 appliedresolved state + price409 catalog changedrefetch and retry422 rejectedreason, previous state keptstateless: every request carries the full state
The 409 path: the version check fails before anything is applied; the SDK retries once with the current version.

Why it happens

Every evaluate request carries the catalogVersion the page booted with. Before touching anything, the engine compares it with the current one. If the page is behind, the engine refuses to apply the change against a stale catalog, so the shopper never sees a price or an option that no longer exists.

What to do

Nothing, if you use the SDK or an embedded link: the SDK reads the current catalog version and retries the same mutation once with it. The shopper's state goes with the retry, so nothing is lost, and you never see the 409. If you call the engine directly, resend the same mutation with the catalogVersion the 409 returned.

The response

HTTP 409
{
  "errors": [
    { "code": "CATALOG_STALE", "message": "Server catalog is 940; client sent 939. Refetch and retry." }
  ],
  "refetchCatalog": true,
  "catalogVersion": 940        // the current version
}

The SDK exposes this as staleCatalog: true on the result it keeps in evaluation.last(); a 200 never carries refetchCatalog: true. There is no SDK event for a 409, because the retry succeeds before anything is reported; evaluation.last() shows the retried mutation as completed.

Frequently asked questions

Does the shopper see anything?

No. The SDK reads the current catalog version and retries the same change once with it; the shopper's state goes with the retry, so nothing is lost. There is no toast and no event for a 409.

How often does it happen?

Only when someone publishes a new version of the system while a shopper has the configurator open. A page that stays open across a publish gets exactly one 409 on its next change.

I call the API directly. What do I do?

Resend the same mutation with the catalogVersion the 409 returned. Treat it as a retry, not an error.

SDK documentation · Admin guide