When the API said yes and the site says no

Our platform accepts things it then ignores. This skill is the list of known cases and the way to check anything at all.

0. Ask before you write — it costs nothing

POST /docs/validate
{"sections": [ … the same list you would PUT to /content-blocks/{id} … ]}

Answers per path: applied, ignored (accepted and does nothing) or unknown (value not understood — a default will be drawn), with the allowed values when the miss is an enum. Nothing is written, no rights are needed.

It does not check that ids exist or that your token may write — those are shop data, and this endpoint deliberately never touches them.

1. Already wrote it? Then: is it really ignored?

A 200 means the write was stored, not that the value is used. Two checks, in order:

1. Re-read the object. GET /content-blocks and look at your value. Gone or changed → the write was rejected in substance.
2. Open the page in a browser. Present in the object but absent on screen → the widget does not read that prop.

⚠️ Level-1 selectors must pierce Shadow DOM. Level-1 own markup renders inside a shadow root; a plain querySelector does not see it — walk element.shadowRoot recursively. A transferred folder (level 3) is real page DOM: plain querySelector works.

2. Known silent failures

Something silently ignored that is not listed here belongs in the area document — backend-3D/docs/api-areas/ — as a named case.

3. Acceptance checklist

Run all of it before telling the owner you are done.

• [ ] the pages you did not touch look unchanged — check the home page and two sections;
• [ ] the page opens by direct URL and by clicking a link inside the site — these are different code paths, and scripts behave differently;
• [ ] after an in-site click: dropdowns open, modals open, timers run;
• [ ] the header holds at several widths, not just yours;
• [ ] no horizontal scrolling on the page body;
• [ ] the cart really accepts an item — press the button, watch the counter;
• [ ] the text is present in the raw HTML (curl and grep for it), otherwise search engines will not see it;
• [ ] images are served through the resizer, not as originals;
• [ ] the owner is told plainly what is a workaround and what is not.

4. Measuring, not guessing

Install a browser in the scratchpad and drive it. Status codes cannot tell you whether a dropdown opens or a header sticks. One run spent 18% of its steps on this, and it was the cheapest 18% in the whole build — every finding that survived came from a measurement, and the one finding that did not survive came from reading code instead.

HTML widget (folder / release) — what "nothing changed" usually means

• `PUT /html-documents/{id}` answers `HTML_PROJECT_USE_RELEASE`. The document has an active release: change it only through a release (POST …/releases with base:"active" + the changed files → PUT bytes → POST …/releases/{rid}/publish). Name/description still go through PUT.
• Files 404 on the site right after publish. Look at the page source: the asset root must be the NEW release (/_html/{doc}/{rid}/). Only the active release is served; old rids answer 404 by design. Hard-reload the page (the html is not cached, the files are immutable per rid).
• Second widget on the same page breaks the first one's images. The script used the global window.VZ_ASSET_BASE, which the last widget overwrites. Read the root from the wrapper instead: document.currentScript?.closest('.vz-body')?.dataset.vzBase (inline) or document.querySelector('.vz-body-<id>')?.dataset.vzBase (external/defer).
• `:root`/`body` styles apply on the site but not in your local file, or vice versa. On the site they are rewritten to .vz-body-{doc} (both inline <style> and the release's .css files). Selectors like body.dark stay untouched — put such classes on your own root element.
• Publish answers 422 `RELEASE_INVALID`. Read report.errors: ref.missing (a path not in the release — check case and folder), ref.outside (../ outside the folder), hash.mismatch (bytes differ from the declared sha — re-upload, the server does not "fix" the digest), file.forbidden, sw.register. Warnings (page.extra, js.assets, img.large) do not block.
• `FILES_PENDING` (409). Some upload_urls were never PUT. Upload them and publish again — the release id stays.
• ZIP rejected as too large. The limit is 60 MB per request; split media into a first release and send the rest with base:"active".
• The page did not change after `transfer.mjs`. Since revision 6 the page is mounted only after a successful publish; a validator error leaves the page untouched — fix the report and rerun.
• A component release is refused `422` with `component.manifest` or `COMPONENT_MANIFEST_INVALID`. A kind=component release must carry component.json next to index.html; the code names the offending field in ref (params[0].key). Keys are ^[a-z][a-z0-9_]{0,31}$, ≤ 32 of them, the file ≤ 16 KB, select needs non-empty options, and a default must be of the parameter's own type. An unknown type is an error on purpose — the type is what decides the escaping.
• A component release is refused with `COMPONENT_TS_ERROR` / `COMPONENT_TS_CONFLICT`. *.ts in a component folder is compiled on publish into a sibling *.js: the error carries file:line:col, the conflict means a hand-written app.js already sits next to app.ts (drop one). Import paths are not rewritten — write "./util.js", the file the browser fetches.
• A component is on the page and shows only defaults. The write path is props.component.ref / props.component.params and nothing else; props.params or ref next to kind is stored, answers 200 and renders defaults. A key that is not in the schema, or a value of the wrong type, is dropped the same silent way — read the page, not the status code.
• A component cannot be placed at all. active_release_id on the document is 0: no published release means no markup and no schema. Publish the folder first; the parsed schema comes back as manifest on the document and on each release, so never read component.json through the gateway.
• Admin canvas shows the block without styles. The canvas loads files through a signed preview root; if you see raw markup, the block was read by an old client — reopen the page editor. On the live site the same document is fine.