Engine response
409 Conflict: catalog changed
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.
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.
Related
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.