Errors

The API returns errors as JSON with the following shape:

{
  "error": {
    "code": "validation_failed",
    "message": "Human-readable description",
    "details": { ... }   // optional, structure varies by code
  }
}

Switch on error.code — it is stable across releases. The message string is human-readable only and may change.

400

Code	Summary	Cause	Resolution
`invalid_reason`	Reason text is required and must be at least 10 characters.	reason field was missing or shorter than 10 characters.	Provide a descriptive reason of at least 10 characters.

401 — Unauthorized

Code	Summary	Cause	Resolution
`unauthenticated`	Request lacks valid authentication.	No valid session cookie and no `Authorization: Bearer vam_live_...` header — or the presented credential is expired or was revoked.	Sign in to set a session cookie, or include a current `Authorization: Bearer vam_live_<key>` header. Rotate the key from /settings/api-keys if it has been revoked.
`invalid_api_key`	The presented Bearer token is not a valid, active API key.	Key was revoked, never existed, or is malformed.	Issue a fresh key at /settings/api-keys.
`session_auth_required`	Endpoint requires a user session; API keys are rejected here.	The endpoint is UI-only (e.g. AI chat authoring) and does not permit programmatic callers.	Call the endpoint from a signed-in browser session.

402 — Payment Required

Code	Summary	Cause	Resolution
`quota_exceeded`	Org has exhausted its render quota for the current billing period.	`usage_events` + plan cap exceeded; `quotaService.tryConsume` returned !ok.	Upgrade the plan or wait for the next billing cycle.

403 — Forbidden

Code	Summary	Cause	Resolution
`forbidden`	Caller is authenticated but lacks permission for this action.	Missing required role (e.g. owner), API-key caller on a session-only endpoint, or org has not completed email verification.	Use an owner-role session, switch to a session cookie, or verify the org email.
`no_org`	Authenticated user has no organization membership.	Should not occur post-signup. Indicates a broken membership row.	Contact support.
`feature_disabled`	Feature is not enabled for this org.	Per-org flag (e.g. `is_ai_chat_enabled`) is false, or the global env flag is off.	Contact support to enable the feature or upgrade your plan.

404 — Not Found

Code	Summary	Cause	Resolution
`not_found`	Resource does not exist, was deleted, or is not visible to this org.	ID/slug does not resolve in the caller's org. Cross-org access also returns 404 (not 403) to avoid leaking existence.	Verify the id/slug and the authenticated org.
`org_not_found`	The target organization was not found.	orgId does not match any existing organization row.	Verify the orgId and retry.

409 — Conflict

Code	Summary	Cause	Resolution
`idempotency_conflict`	The supplied `Idempotency-Key` was reused with a different request body.	Server has the key cached but the body hash does not match the previous request.	Use a fresh idempotency key, or replay with the original body.
`slug_conflict`	Could not derive a unique slug after 100 attempts.	Name collides heavily with existing user-block slugs in this org.	Provide an explicit `slug`, or change the `name`.
`org_has_stripe_subscription`	Cannot comp an org with an active Stripe subscription.	The org has stripeSubscriptionId set and subscriptionStatus in ('active','trialing','past_due','unpaid'). Comping a paying customer would create ambiguous entitlement state.	Revoke or cancel the Stripe subscription first, or use the Stripe portal to manage the customer.
`org_has_no_active_comp`	Cannot revoke — org has no active comp grant.	is_comped is false or no non-revoked grant exists for this org.	Check the org's comp status before calling revoke.

413 — Payload Too Large

Code	Summary	Cause	Resolution
`context_too_large`	AI chat input exceeds the model's context budget.	Block config + chat history + user message do not fit the token budget after trimming.	Shorten the chat history or simplify the block config.

422 — Unprocessable Entity

Code	Summary	Cause	Resolution
`validation_failed`	Request body or params failed Zod validation.	A required field is missing, has the wrong type, or violates a constraint (slug regex, op-list structure, legal pointer, etc.). Also used for domain-specific validation failures (e.g. slug already in use returns 409 with this code).	Inspect the `error.details` field for Zod issues or a `fields` list describing the violated path.
`user_block_invalid_config`	User-block `config` does not match the schema for its `kind`.	For `kind: 'layoutCellBlock'`, the `config` did not parse as `LayoutCellBlockConfig` (cell types, geometry, animations, etc.).	Inspect the appended Zod issue in `error.message` and fix the offending cell config.
`parameter_path_invalid`	A parameter path on a user block must begin with `/`.	Supplied `parameters[].path` did not start with `/` (JSON-pointer form required).	Prefix the path with `/` (e.g. `/cells/abc/content/text`).
`brand_kit_music_missing`	Format references a brand-kit audio slot, but the brand kit has no uploaded music.	An `audioTracks[i]` has `source: 'brand_kit'` and the resolved brand kit's `musicSpacesKey` is null.	Upload music to the brand kit, or change the audio slot's source.
`legacy_format_ops_locked`	Cannot patch `ops` or `openContentPaths` on a legacy-template format.	The format has `sourceKind: 'legacy-template'`, which is immutable at the op-list level.	Create a new block-composer format via POST /v1/formats, or patch only legacy-safe fields (name, brandKitId, status).
`missing_required_variable`	A required parameter was not provided in variables.	The block defines a parameter with no defaultValue and the caller omitted it.	Check the block's /schema endpoint for the full parameter list; include all required names in `variables`.
`invalid_variable_type`	A provided variable's value doesn't match its parameter's declared type.	e.g. you sent a string for a `number` parameter, or an invalid hex for a `color`.	Look up the parameter's type via the /schema endpoint and coerce the value accordingly.
`parameter_path_stale`	A parameter's path points at a cell field that no longer exists.	The block was structurally edited after the parameter was marked; the target cell or field was renamed or deleted.	Open the block in the canvas designer and re-mark the parameter, or remove the stale parameter entry.
`parameter_name_duplicate`	Two parameters within the same block share a name.	Parameter names must be unique per block so the variables map is unambiguous.	Rename one of the conflicting parameters.
`unknown_variable`	Request sent a variable name that is not declared on the format.	Typo in the variable name, a locked binding's name, or a name that was renamed/removed since the caller generated their integration.	Fetch GET /v1/formats/:slug/schema for the current variable list and align naming.
`variable_ambiguous`	Bare-name variable shortcut matches multiple bindings.	The caller sent e.g. 'player.name' on a format that exposes both 'game1.player.name' and 'game2.player.name'. The shortcut only resolves when exactly one binding matches.	Use the scoped name (e.g. 'game1.player.name'). error.details.fields[].alternatives lists valid options.
`variables_and_overrides_exclusive`	Request body includes both 'variables' and 'contentOverrides'.	Only one envelope may be used per request. 'variables' is the flagship named-parameter shape; 'contentOverrides' is preserved for legacy raw-pointer integrations.	Pick one envelope. Prefer 'variables' — fetch GET /v1/formats/:slug/schema for the variable contract.
`duplicate_instance_label`	Two user-block instances in the format share an instanceLabel.	Instance labels must be unique within a format because they scope public variable names. Editor blocks this client-side; defense-in-depth at the server PATCH validator.	Rename one of the duplicates in the format editor.
`user_block_op_immutable`	Cannot mutate op.content on a user-block instance op post-drop.	format.ops is an immutable template after a user block is dropped. Data edits must flow through parameter_bindings + default_overrides. Design changes must happen in the block designer.	Use the instance-edit panel (which auto-parameterizes) or, for design changes, edit the source user block in the canvas designer and use the updateInstance PATCH flow.
`unsupported_parameter_field`	Field type is not supported for parameter binding.	pathTypeCompatibilityMap has no entry for this cell field + target parameter type. The editor refused to auto-create a binding because it cannot infer a safe coercion.	Parameterize a supported field on the cell, or change the cell kind in the block designer.

429 — Too Many Requests

Code	Summary	Cause	Resolution
`rate_limit_exceeded`	Per-user or per-org rate limit exceeded.	Image upload bucket (20/hr/user) exhausted, or AI-chat daily cap hit. See `error.details.limit` / `retryAfterSeconds` / `resetsAtUtc` for specifics.	Wait for the window to reset and retry.
`daily_limit_exceeded`	AI chat daily message cap reached for this user.	Cap is plan-tier-derived; `error.details.currentTier` / `nextTier` / `nextTierCap` / `upgradeUrl` surface the upgrade path.	Upgrade the plan or wait until the UTC-midnight reset (`error.details.resetsAtUtc`).
`retry_too_frequent`	Thumbnail retry throttled — wait 60 seconds.	User block thumbnail retry invoked less than 60s after the previous attempt.	Wait the cooldown and retry.
`thumbnail_rate_limit_exceeded`	Per-org thumbnail render rate limit exceeded.	Thumbnail renders in the trailing 60-minute window exceeded the org's cap.	Wait for the window to roll forward, or reduce concurrent retries.

500 — Internal Server Error

Code	Summary	Cause	Resolution
`tool_loop_limit`	AI chat tool-use loop exceeded the max iteration cap.	The model requested too many tool turns without converging.	Restart the chat turn with a narrower user message.
`internal_error`	Unhandled server error.	Unexpected exception inside a route handler or service.	Retry with backoff. Persistent errors should be reported to support with the response timestamp.

502 — Bad Gateway

Code	Summary	Cause	Resolution
`anthropic_api_error`	Upstream Anthropic API call failed after retries.	Transient or model error from the Claude API during a chat turn.	Retry the request. Persistent failures indicate an upstream incident.

The full interactive reference with per-endpoint error codes is in the API Reference.