Engine response

422: rejected by a constraint

, imagine.io ·

What it means. A constraint refused the change. A maximum count was reached, a required neighbour is missing, a fixed position would be broken, or a custom condition you wrote said no. Nothing changed on the engine's side; the previous configuration stands.

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 422 path: a constraint fails at step 4; nothing is applied, and the page gets the reason.

Why it happens

After every mutation the engine applies the matching rules and then re-checks every constraint attached to the system. A constraint is a condition that must always hold, whatever was chosen, so a selection that was fine a moment ago can become invalid when a later choice breaks it. When one fails, the engine answers 422 with the code CONSTRAINT_VIOLATION_HARD, the id of the constraint that refused and a sentence for the shopper, and keeps the state it had.

What to do

With the SDK: nothing. It rolls back the optimistic paint, keeps its current state, shows errors[0].message as a toast and fires evaluate.rejected. In an iframe, the parent page receives the same as a configurator:event. One thing is yours: if your page has already added a cart line or updated a price on the change, roll it back on this event, not on the command's reply, because a command can be accepted by the bridge and refused by the engine a moment later.

import { on } from '@imagineio/configurator-sdk';

on('evaluate.rejected', ({ mutation, code, errors, internal }) => {
  if (internal) return;                               // the SDK's own focus re-evaluate; never shown
  track('constraint_hit', { type: mutation.type, code, message: errors[0]?.message });
  cart.rollbackPendingLine();                          // your page's part
});

// In an iframe on a store page
window.addEventListener('message', (e) => {
  const m = e.data;
  if (m?.type === 'configurator:event' && m.event === 'evaluate.rejected') showNotice(m.data.errors?.[0]?.message);
});

The response

HTTP 422
{
  "code": "CONSTRAINT_VIOLATION_HARD",
  "errors": [
    { "code": "CONSTRAINT_VIOLATION_HARD",
      "message": "Too many base units: max 6 per scene, got 7.",
      "details": { "constraintId": 318, "max_count": 6, "actual": 7, "scope": "scene" } }
  ],
  "blockingMutation": true,
  "previousState": { "...": "the state the engine kept, same shape as resolvedState" },
  "warnings": [],
  "catalogVersion": 940
}

On a 422 every field that describes the configuration is null: resolvedState, pricing, the option maps. Check applied first; reading pricing.grandTotal on a rejection throws.

Frequently asked questions

Is a 422 an error I should log?

It is the engine doing its job, not a fault. Log the code if you want to know which constraints shoppers hit most, since that is useful product data, but do not alert on it.

Which codes exist?

Every constraint rejection carries the code CONSTRAINT_VIOLATION_HARD, whether the constraint is built in or custom; errors[0].details.constraintId says which constraint refused, and errors[0].message is the sentence to show (for a custom constraint, the message you wrote in the dashboard). Codes such as INVALID_PLACEMENT_ID or INVALID_VARIANT are also 422s, but they mean the mutation itself was malformed, not that a constraint said no.

Can a rule, not a constraint, cause a 422?

No. Rules react to a change and shape the result; they appear in a 200 as overrides, hidden options and messages. Only a constraint refuses a change. The difference is explained in rules versus constraints.

SDK documentation · Admin guide