Theme errors come in two shapes:
  • Per-file errors in a write’s user_errors. The rest of the batch was still written, and the call succeeded. Fix the listed files and write them again.
  • Request errors in the Gateway envelope: { "success": false, "message": "…", "error_code": "…" } with an HTTP status. Nothing was done.

​
PLATFORM_OWNED

The file belongs to the platform’s store template. Platform files are updated by PlatformDTC for every store, so a theme cannot change them — and rather than accepting your write and reverting it on the next publish, it is refused now. Fix: build the change in a file you own.
  • A different section → write a custom section in theme/custom/sections/<type>.tsx and use custom-<type> in the template.
  • Different settings or order → edit templates/*.json or the section group.
  • Styling → styles/merchant.css.
  • Layout wrappers → components/store-layout.tsx or components/store-providers.tsx.
get_theme_manifest lists every file with its owner and editable.

​
IGNORED_PATH

The path is under node_modules/, .next/, out/, .git/ or data/. These are build output or are generated from your catalog on every publish. Change the source instead — for product data, edit the product.

​
INVALID_PATH and TOO_LARGE

Paths must be relative, use /, contain no .., not start with /, be at most 256 characters, and end in one of .json .tsx .ts .css .md .svg .png .jpg .jpeg .webp .gif .woff2 .ico .txt. A file may be at most 2 MiB, and a write at most 50 files — split larger changes into several writes. TOO_LARGE also means the write would take the theme’s workspace over 500 MiB in total (node_modules/, .next/, out/ and .git/ do not count). Splitting the write does not help here: compress or resize images and fonts, or delete assets the theme no longer uses, then write again.

​
CONFLICT

You sent checksum_before, and the file has changed since you read it — the merchant saved in the theme editor, or another agent wrote it. Your write for that file was not applied, so their change is safe. Fix: read the file again, apply your change to the current content, and write it with the new checksum. Do not drop checksum_before to force the write; that overwrites someone else’s work.

​
INVALID_JSON and INVALID_TEMPLATE

A templates/*.json, sections/*-group.json or config/settings_data.json file did not parse, or is not a valid Builder2 document — for example more than 25 sections, blocks nested deeper than 8, or an id in order with no section. line and column point at the problem when available. See the template JSON reference.

​
NOT_FOUND

The theme or file does not exist, or is not in the store your token is for. Development themes are deleted after 7 days without changes — list the themes and create a new one if yours has expired.

​
CHECK_FAILED

HTTP 422 from a publish: theme check found errors, and nothing was published or queued for approval. Each error names its rule, path and usually a line and hint. Common causes:
  • tsc — TypeScript errors are warnings while you develop and errors on publish. Run check_theme (or dtc theme check) before publishing so you see them early.
  • import-resolves — a custom section imports a package that is not available. Use @/theme.
  • no-placeholder-text, no-placeholder-link, no-empty-image — sample content or an empty link or image. Remove it or replace it with the real value.
Fix, check again until ok is true, then publish.

​
CHECK_BUSY

429 with a Retry-After: 5 header, from check_theme, get_theme_manifest (and get_section_schemas) or publish_theme: theme check is at capacity. Each store runs at most one check at a time, and the platform caps how many run at once. Nothing was checked or published. Fix: wait the Retry-After seconds and send the same call again. Run checks for a store one after another, not in parallel. The CLI waits and retries on its own before reporting CHECK_BUSY.

​
pending_approval

Not an error. The store requires the merchant to approve agent publishes, so the publish is waiting. The merchant approves it under Settings → Developer → Build with your agent → Theme publish approvals. Do not publish again while it waits — follow it with get_publish_status. See Scopes and approvals.

​
Publish returns an existing job

Not an error. If a publish of the same theme is already queued, waiting for approval or running, publish_theme does not start another one: it answers 200 (instead of 202) with that job.
Follow that job with get_publish_status (dtc theme publish follows it for you).

​
THEME_IS_LIVE

409. The theme is the store’s live (main) theme, and agents cannot change it directly.
  • From a write — write_theme_files, delete_theme_files or rollback_theme (PUT /themes/{id}/files, POST /themes/{id}/files/delete, POST /themes/{id}/rollback), or dtc theme push, dtc theme dev and dtc theme rollback against the live theme. Nothing was changed. This applies to every agent key and OAuth connection, including the CLI; the merchant can still edit the live theme in the dashboard. Fix: create a development theme (create_dev_theme, or dtc theme dev), make the change there, check it, then publish it (publish_theme, or dtc theme publish --theme <id>).
  • From deleting a theme — the live theme cannot be deleted. Publish another theme first.

​
BUILDER1_NOT_SUPPORTED

409 on any write, rollback, dev-theme creation or publish. The theme was built with the classic page builder, whose pages are free-form code. Agents work only on Builder2 themes, where layout is template data and custom code is limited to custom sections. Fix: in the dashboard, go to Themes → New theme to create a Builder2 theme, then have your agent create a development theme from it (create_dev_theme with from_theme_id). Reading a Builder1 theme (list, manifest, read files, check) still works.

​
THEME_NOT_DEVELOPMENT

409 from delete_theme (DELETE /themes/{id}): agents can delete only development themes. The theme is unpublished, and nothing was deleted. Fix: leave it, or ask the merchant to delete it in the dashboard.

​
THEME_LIMIT

409 from create_dev_theme (POST /themes): the store already has as many development themes as it may hold — 10 unless the platform set a different limit. No theme was created. Fix: reuse an existing development theme (list_themes, or dtc theme list), or delete one you no longer need (delete_theme, or dtc theme delete --theme <id>) and create the theme again. Development themes are also deleted automatically after 7 days without changes.

​
FORBIDDEN_SCOPE

403: the token lacks the scope for this call — for example publishing without publish_themes. For an OAuth connection, reconnect and grant the scope on the consent screen. For a static key, create a key with the scope.

​
401 Unauthorized

The token is missing, expired or revoked. OAuth access tokens last one hour; clients refresh them automatically. If refreshing fails, sign in again — in Claude Code run /mcp, in Codex run codex mcp login platformdtc-theme, with the CLI run dtc login.

​
IDEMPOTENCY_CONFLICT

409: an Idempotency-Key was reused with a different request body. Use a new key for every distinct write.