Tool errors

InBlack tool results use structured uppercase INBLACK_* codes. Do not parse older snake-case examples or infer an HTTP status from a tool error.

Result envelope

The MCP response contains a text item whose text is a JSON-serialized ToolResult:

{
  "status": "error",
  "error_code": "INBLACK_VALIDATION_ERROR",
  "tier": "T3",
  "summary": "No active organization set. Use inblack_set_org first."
}

The result contract is:

Field	Meaning
`status`	`ok`, `error`, or `needs_confirmation`
`summary`	Human-readable outcome
`error_code`	Optional machine-readable code
`tier`	Effective tool tier when relevant
`data`	Optional structured data
`preview`, `preview_hash`	Optional action preview
`pending_action_id`	Pending action to confirm or reject
`warning`	Optional caution or degraded-mode message
`provenance`	Optional causal metadata

The MCP tool response sets isError: true only when status is error. A queued action uses status: "needs_confirmation" with INBLACK_CONFIRMATION_REQUIRED, so clients must inspect the parsed result rather than relying only on MCP isError.

Declared codes

The Worker currently defines:

Code	Meaning and client action
`INBLACK_UNAUTHORIZED`	Authentication is absent or unusable; obtain a valid credential
`INBLACK_FORBIDDEN`	The principal, policy, surface, or execution context denies the operation; do not retry unchanged
`INBLACK_VALIDATION_ERROR`	Arguments or required context are invalid; correct the request
`INBLACK_NOT_FOUND`	Requested resource or pending action was not found; verify identifiers and tenant
`INBLACK_CONFLICT`	Current state conflicts with the operation; re-read before deciding whether to retry
`INBLACK_IDEMPOTENCY_CONFLICT`	An idempotency key was reused with different intent; use the original request or a new key
`INBLACK_UNKNOWN_COMPONENT`	A referenced storefront component is unknown; use a supported component
`INBLACK_CONTRACT_VIOLATION`	Input violates a storefront or generated contract; correct it
`INBLACK_VERSION_CONFLICT`	Supplied version is stale; fetch the current version and reapply the change
`INBLACK_NOTHING_TO_PUBLISH`	Publish request has no eligible change; do not retry unchanged
`INBLACK_DOMAIN_TAKEN`	Requested domain is already assigned; choose or release a domain
`INBLACK_DNS_UNVERIFIED`	Domain DNS proof is incomplete; fix DNS and verify again
`INBLACK_QUOTA_EXCEEDED`	Tenant or feature quota is exhausted; reduce usage or change entitlement
`INBLACK_RATE_LIMITED`	A runtime limit was reached; follow returned guidance before retrying
`INBLACK_T4_BLOCKED`	Destructive execution is blocked on this surface or by policy
`INBLACK_CONFIRMATION_REQUIRED`	The action needs approval or cannot be queued in this context
`INBLACK_NOT_IMPLEMENTED`	The selected delegate or workflow is not implemented; use another supported path
`INBLACK_BACKEND_ERROR`	Downstream or unclassified execution failure; retry only when the operation is safely idempotent
`INBLACK_AUDIT_UNAVAILABLE`	Required audit/provenance emission failed; the Worker fails closed for governed writes

The manifest’s error_codes array lists the declared subset for each tool. It is better input for generated clients than assuming every code applies to every tool.

Confirmation is a state

A queued write returns:

{
  "status": "needs_confirmation",
  "error_code": "INBLACK_CONFIRMATION_REQUIRED",
  "tier": "T3",
  "pending_action_id": "pending_...",
  "preview": {},
  "preview_hash": "...",
  "summary": "Created pending action ..."
}

Retain the ID and preview, present the proposal to the user, then call inblack_confirm_action with approved: true or approved: false. Do not repeat the original write merely because it has not executed.

In a context that cannot queue actions, the same code can arrive with status: "error" and no pending-action ID. Move the workflow to an interactive approval-capable context.

Visibility and unknown tools

Hidden tools are not registered in public request discovery. A direct call to an unregistered name can therefore fail at the MCP protocol layer as an unknown tool rather than returning a tool-level authorization envelope.

Public T4 attempts are recorded before protocol dispatch, but T4 tools remain unregistered and blocked. Never use repeated probing to discover hidden tools; use the filtered manifest and tools/list.

Transport errors

Authentication and routing can fail before MCP tool dispatch. Those HTTP JSON responses use lower-case transport errors such as:

Error	Typical status	Meaning
`missing_bearer_token`	401	No bearer credential
`invalid_bearer_token`	401	JWT verification failed
`insufficient_scope`	403	Internal MCP credential lacks internal access
`tenant_required`	400	Internal MCP request omitted `X-Tenant-ID`
`tenant_policy_unavailable`	403	Tenant policy could not be verified
`method_not_allowed`	405	Public `/mcp` received a method other than POST
`legacy_sse_retired`	410	Client used `/sse` or `/messages` on the public alias

Keep transport handling separate from parsed ToolResult handling.

Retry rules

Never retry a write blindly. Send an idempotency_key where the schema provides one.
On INBLACK_CONFLICT or INBLACK_VERSION_CONFLICT, re-read state before rebuilding the request.
On INBLACK_RATE_LIMITED, use returned timing or summary guidance; do not assume a fixed delay.
On INBLACK_BACKEND_ERROR, retry only with bounded backoff and idempotency protection.
Do not retry validation, authorization, quota, destructive-block, or not-implemented failures unchanged.
Treat INBLACK_AUDIT_UNAVAILABLE as fail-closed; do not bypass the governed tool path.