Errors

Match on the code, not on the HTTP status. Vault API errors arrive as:

{ "error": { "code": "MANIFEST_INVALID", "message": "…", "retryable": false } }

The vault SDK raises them as VaultRequestError with status, code, and retryable. Retry only when retryable is true.

Connecting an agent

Code	Status	Meaning	Fix
`MANIFEST_INVALID`	400	A requested scope is not in the manifest’s `requiredScopes`, the agent id does not match the manifest, or the manifest’s `kind` is invalid.	Connect into a declared scope, or push a version that declares it.
`MANIFEST_NOT_FOUND`	404	No manifest for that agent id in the registry.	Check the id; push the agent.
`SETTINGS_SCHEMA_MISMATCH`	400	Settings do not satisfy the agent’s settings schema.	Fix the values.
`AGENT_ALREADY_CONNECTED`	409	A connection already exists.	Use it.
`BUNDLE_CHANGED`	409	The `bundleCid` you named is not the agent’s current bundle. Nothing was stored.	Show the new code; connect again with its CID.
`RECONSENT_REQUIRED`	409	A reconnect would run different code than the owner consented to, and no `bundleCid` was given.	Ask for consent; connect with the new `bundleCid`.
`GAR_MISSING`	412	No consent agreement.	Connect again; it signs one.
`GAR_EXPIRED`	412	The agreement was revoked or expired.	Connect again.
`CUBBY_PROVISION_FAILED`	500	A cubby migration failed.	Fix it in a new migration file and push a new version.
`AGENT_NOT_CONNECTED`	404/409	The agent has no connection in this vault.	Connect it.
`ROLE_CONFLICT`	409	A connection can hold only one role (workflow agent, harvester, analyzer, embedder).	Clear the other role first.
`SETTINGS_STALE`	409	The settings changed since you read them.	Re-read and retry.

See Connect to a vault.

Authentication

Code	Meaning
`AUTH_MISSING`	No signature or credential on the request.
`AUTH_AMBIGUOUS`	The request carries more than one auth scheme, or a principal that cannot perform the action (an agent deleting a vault object, for example).
`INVALID_SIGNATURE`, `SIGNATURE_EXPIRED`	The request signature is wrong or too old. Check the clock.
`AUTHTOKEN_INVALID`, `AUTHTOKEN_EXPIRED`	The bearer token is invalid or expired. Generate a new one.
`NOT_VAULT_OWNER`	The action is owner-only.
`SCOPE_DENIED`	The caller may not perform this action in that scope.

Events, objects, and registry

Code	Meaning
`PAYLOAD_TOO_LARGE`	The event or object is too big. Store large data as an object and publish its path.
`DUPLICATE_EVENT_ID`	A publish was rejected because an event with that id already exists. Safe to treat as already delivered.
`VAULT_DISCONNECTED`	The vault’s storage credential can no longer be refreshed.
`ALIAS_NOT_YOURS`	`cef push --vault`: the alias belongs to another publisher.
`REGISTRY_UNAVAILABLE`	`cef push --vault`: the registry could not be written. Retryable.
`CUBBY_UNAVAILABLE`	A cubby read or write failed.
`SCHEDULE_NOT_FOUND`	No such schedule on the connection.
`CONNECTION_*`, `CONNECTOR_UNKNOWN`	Connector connection errors. See Connectors.
`WEBHOOK_UNAUTHORIZED`	Webhook call with an unknown endpoint or a bad, revoked, or expired key. One answer for all, by design.
`WEBHOOK_CREATOR_NO_ACCESS`	The key’s creator can no longer write the scope.

Vault SDK exceptions

Exception	Meaning
`BundleChangedError`, `ReconsentRequiredError`	The two 409s above, with `currentCid`.
`OnboardingRequiredError`	`ensure()` needs the wallet’s on-chain gateway registration first.
`OnboardingTimeoutError`	Onboarding did not finish in time. `ensure()` is idempotent; retry.
`VaultSignerRequiredError`	The method needs a `signer`.
`CeilingUnknownError`	A member scope write needs the member’s privacy ceiling; pass it in `standing`.
`vault.agents.connect requires \`garEndpoint``/`a `signer``	Configure both on `VaultSDK`.

Widgets

Error	Meaning
`AgentNotConnectedError`	The reader’s vault has not connected the widget’s agent. Offer `connectAgent()`.
`WidgetSignedOutError`	The host did not answer the identity handshake. Mount `createWidgetHost` on the framing page.
`WidgetVaultUnreachableError`	The named vault cannot be opened by this reader.
`WidgetWalletUnconfiguredError`	The manifest has no wallet origin. Push with `--env` so endpoints are written.

CLI

Message	Meaning	Fix
`This DDC access token can't write bucket <id>: it is signed by … but the bucket is owned by …`	The token is not rooted in the bucket owner.	Get Invite to publish; see Team.
`This DDC access token expired at …`	Expired token.	Generate a new one in ROC.
`bucket <id> does not exist on this network`	Wrong `--bucket` or `--env`.	Check both.
`choose a destination: --bucket … or --vault …`	No destination.	Pass one.
`--card is required for an external agent`	`--kind external` without a card.	Pass `--card`.
`… describes an external agent — pass --kind external`	A flag for the other kind.	Fix the flags.
`bundle not found … run \`cef build` first`	Nothing built.	Run `cef build`.
`multiple built agents in dist … pass --agent <id>`	Several agents built.	Pass `--agent`.
`no CLI access token`	`deploy`/`publish` without a token.	Set `CEF_ACCESS_TOKEN`.
`"weight" must be a positive integer (>= 1)`	Deployment weight.	Use integer shares like `90` and `10`.
`all default records (empty targeting) must share one priority tier`	Defaults at different priorities.	Keep exactly one default record.
`banned import "<module>"`	Node built-in or banned package.	Use sandbox globals.
`@OnEvent argument must be a string literal`	Computed event type.	Use a literal.
`ctx.models.<alias> is not declared in cef.config.ts models`	Undeclared model.	Add it to `models`.
`schedule "<id>" publishes "<type>", which this agent does not handle`	Schedule event unhandled.	Add an `@OnEvent` for it.
`workflow "<id>" is not runnable`	`defineWorkflow` validation.	Fix the listed steps.
Exit code `2` from `cef inspect`	A routed handler is missing from the bundle.	Add the handler.

Deployments API

Code	Status	Meaning
`validation_failed`	400	The set broke a rule: names, weights, versions, targeting that does not compile, or not exactly one default record. The message names it.
`revision_conflict`	409	Another apply landed first. Re-read and apply again.
`apply_failed`	500	The platform could not store the set.

Runs

A Task that fails carries an error.code:

Code	Meaning
`execute_failed`	The runtime call failed: the handler threw, or the call could not complete.
`execute_timeout`	The task ran past its time budget.
`running_lease_expired`	The task was claimed but never reported back; it is retried.
`job_terminated`	The Job ended while the task was pending.
`agent_invalid_result`	The handler returned a value that does not survive JSON serialization, such as a circular reference.
`agent_threw_non_error`	The handler threw a non-`Error` value. Throw an `Error`.
`agent_returned_undefined`	The bundle’s handler returned nothing the runtime could read.
`gpu_units_ceiling`, `a2a_tokens_ceiling`	The connection reached its spend limit; see Spend limits.

A Job ends with a reason: revoked, idle_timeout, closed_by_agent, or failed. @OnClose receives it.

Gateway code	Status	Meaning
`NO_RUNTIMES`	503	No agent runtime is available.
`FLEET_SATURATED`	503	Every runtime is busy. Retry later.