Envelope and errors

Read a successful response

{
  "ok": true,
  "data": {},
  "meta": { "trace_id": "00000000-0000-0000-0000-000000000000" }
}

Successful responses carry ok: true, capability-specific data, and metadata. State-bearing results can also carry web_url, which points to the related object in the app while the JSON id remains the source of truth.

Read a refusal

{
  "ok": false,
  "error": {
    "code": "mode_required",
    "message": "A mutating call requires mode: smoke_test, dry_run, or live.",
    "details": {}
  }
}

Failures carry an error object with code, message, and optional details. Handle the code in software and use the message and details to guide a person or agent to the repair.

Repair by code, not message text

mode_required means that a mutating call needs an explicit mode. capability_not_fetched means you must search or get the capability in the current turn. quote_required means a priced live call needs its returned quote and a credit ceiling.

Show me the error code from this failed run, the repair in its details, and the exact request I should retry.

Keep envelope fields separate from result fields

The envelope is common across catalog discovery and execution, while the contents of data are capability specific. Branch on ok before reading data. Then use the fetched output schema to interpret names, ids, status values, records, receipts, or run references inside the successful result.

Do not assume every success has the same data keys. A tool search can return candidates, runnable contracts, and a tool-turn token. A tool get returns an exact capability descriptor. A capability run can return a business result, a receipt, a run reference, or another output shape defined by that contract.

Metadata identifies the response and its gateway context. The trace id is useful when an operator needs to connect an observed response to support investigation. It is not a capability id, a retry identity, a credit quote, or a replacement for a state-bearing result identifier.

State-bearing data can include web_url. Use that app URL to inspect the object shown to a person, but preserve the returned JSON ids for programmatic reads. A web URL is navigation evidence, not the canonical identity of a workspace object.

Common error codes and repairs

A failure begins with ok: false. Read error.code as the stable program-facing branch, then use error.message and optional structured details to present the repair. Do not parse a human message to invent a new request, because the code distinguishes input repair, discovery repair, pricing, security, and provider-specific states.

mode_required means a mutating request omitted the execution mode. Select a mode supported by the fetched contract. The server never chooses live by default. Use smoke_test for static policy inspection, dry_run for real workspace validation without a business write, and live only for deliberate execution when the contract permits it.

capability_not_fetched means the current turn did not receive the contract for the id being run. Search or get the exact capability again, keep its returned turn token, and run the supplied schema. A remembered id, a marketplace profile, or a skill instruction is not a substitute for discovery.

quote_required means a priced live operation needs the estimate returned for the same request and a maximum-credit ceiling. Do not change the capability parameters while accepting the quote. If the intended work changed, fetch and price the changed contract rather than retrying an old quote.

invalid_request means the envelope or capability input failed the published schema. Use the details and the current descriptor to correct field names, types, or required values. A malformed tools-run body receives a repair instructing the caller to match its published schema before retrying.

not_found means the named current resource or metadata object was not found. For a pack, list the active packs before retrying get. For a state-bearing result, retain returned JSON ids and the selected workspace rather than constructing a path from a human label.

Work through a response safely

First read ok. On success, preserve the data ids and trace id, then decide whether the result is final or points to an asynchronous run. On failure, preserve the code, message, details, trace id, and request identity so a person or client can make one evidence-based repair instead of sending a second ambiguous request.

For a search response, inspect the returned candidate id, pack, and runnable contract. For a get response, inspect the input and output schemas before creating params. For a run response, inspect the returned business result or run reference before interpreting a client timeout as failure.

If a response reports a run id, use run reads and events to learn its state. An asynchronous operation is not necessarily failed because its first envelope is not terminal. Preserve the run id and the original request identifiers instead of issuing a duplicate execution while the returned run remains the source of truth.

If an external provider change completed but its local finalization did not, a capability can return reconciliation_required. Inspect the provider state and the local result before retrying. The envelope reports the machine-readable condition, while the fetched capability contract explains its own reconciliation semantics.

Use idempotency for a retryable live mutation. The retry key is not the trace id or tool-turn token. See Idempotency for header and body placement, root-action rules, and durable receipt fields. Keep the same key when retrying the same uncertain execution.

Read this response envelope. Report ok, trace id, data ids or error code, the repair from details, and whether the result requires a run-status read. Do not retry until you identify the exact failure class.

When it goes wrong

If the response has ok: false, do not read it as a successful data shape. Branch on error.code, retain trace id and details, and make the repair the code names. A 400 does not identify one universal cause: it can be malformed input, missing mode, missing idempotency, or another explicit refusal.

If a tool token is expired or the catalog changed, start new discovery and use the current descriptor. If a sender, provider connection, or recipient field is blocked, correct the condition in the owning pack before retrying. An envelope error is evidence about the failed request, not permission to bypass another policy.

If a live request needs a quote, preserve its parameters and add the intended credit ceiling. If it is an owner action, use the signed-in session and fresh approval path with an idempotency key. These are distinct repairs, and the envelope's code tells a client which one applies.

If a client lost the response after sending a mutation, inspect the returned run or durable receipt where the capability exposes one before retrying. Retrying with a new idempotency key because the response was lost can create a separate operation rather than recovering the earlier attempt.

Keep the envelope alongside the request context. The selected workspace, capability id, execution mode, and returned trace id make an error actionable without treating a generic message as evidence of another result.

A success envelope does not mean every downstream provider result is permanent. Read the capability-specific fields and any run state that it returns, particularly when a contract declares asynchronous execution.

A failure envelope does not expose a replacement capability. Return to discovery if the failure identifies a stale or unfetched contract, then validate the new descriptor rather than substituting a similar id.

The message is for people, while the code is for stable branching. Preserve both, because a user needs the explanation and a client needs a reliable classification for retry, recovery, or stop behavior.

Use structured details only as the response supplies them. Do not presume that every error includes the same nested fields, because details are optional and capability-specific evidence can differ by refusal class.

A response can help an agent choose the next read without authorizing a write. Search, get, and result state are evidence surfaces; a later mutation still needs its fetched contract and applicable execution controls.

For an ordinary live capability, credits and a maximum ceiling govern priced work. For owner changes, signed-in authority and a fresh approval govern security. The envelope reports which condition prevented execution.

If a server returns a provider-specific error, retain its code and returned details with the trace id. Then inspect the connected provider, recipient, or workspace state named by the fetched capability contract.

Never replace a failed response with a fabricated success record. The canonical envelope is the only response evidence a client has until a later read, receipt, or run-status response confirms the outcome.