Error reference

The request shape was rejected: a field is missing, malformed, or out of range.

Recover: Fix the flagged field against the tool's input schema and retry.

No artifact resolved for the given id in this workspace.

Recover: Check the id; the envelope's details carry ranked suggestions of close matches you likely meant.

The parent you linked isn't an allowed parent for that child type; parenting is type-by-shape.

Recover: Read artifact_types (or hf://types) for the child's allowedParentTypes, pick a valid parent, and retry. Nothing was written.

An LLM-backed step couldn't reach the AI gateway (down, rate-limited upstream, or unconfigured).

Recover: Retry shortly; if it persists, the operation can proceed without the AI-graded step.

An unexpected server-side failure the caller can't correct.

Recover: Retry once; if it persists, report it via send_feedback with the request details.

A read-only tool could not reach the datastore needed to answer accurately.

Recover: Retry shortly. Do not interpret the failed response as an empty result; the underlying facts were not read.

A proposed change was declined or never applied.

Recover: Nothing landed. Revisit the proposal or adjust it before requesting another decision.

You're authenticated but not a member of the target workspace (403, not 404; the workspace exists).

Recover: Use a workspace you belong to, or have an admin invite you.

The result exceeded the response cap and was withheld or degraded.

Recover: Narrow the request: add filters, lower the limit, page with offset, or pass a slimmer shape.

Too many requests in a short window.

Recover: Back off and retry after a short delay.

An optimistic-concurrency conflict: the base you edited against had already moved on.

Recover: Re-read the current state and re-apply your change on top of it.

The workspace itself didn't resolve (distinct from missing membership).

Recover: Check the workspace id in the URL / pin; use a valid workspace.

The primary write succeeded but a declared side-effect didn't; the operation is retryable and convergent.

Recover: Re-issue the identical call; it keys off live state and completes the outstanding side-effect without duplicating the primary write.

You're authenticated, but this operation isn't permitted for your execution context (the action verb is outside the proposable allowlist, or its payload doesn't fit the allowlist entry's contract).

Recover: Read the details: `restricting` names what scoped the refusal and `next_step` says whether to amend and resubmit, await review, or abandon.

You're a member of this workspace, but your role carries no write capability, so tools that mutate workspace content are refused. `details.tool` names the tool that was refused.

Recover: Don't retry and don't reshape the call — nothing about the request will change the outcome. Read tools still work. A workspace admin must grant write access.