Error codes

This page is the long-tail dictionary: every SHROUD_* code the gateway can emit, its HTTP status mapping, and a one-line description. The table is auto-generated from pkg/errcode/codes.go on every release — do not edit it by hand.

For the envelope shape (where these codes appear in the JSON response), the per-transport notes (HTTP / MCP / JSON-RPC / Cocoon WebSocket), Retry-After semantics, and request_id correlation, see Error reference. For caller-side action mapping (when to retry, when to surface, when to alert), see Production guide — Error handling map.

Code	HTTP	Description
`SHROUD_BATCH_TOO_LARGE`	400	Batch exceeded maximum allowed inner calls.
`SHROUD_CONFIRMATION_EXPIRED`	410	Confirmation token expired, already used, or did not match the resubmitted arguments.
`SHROUD_CONFIRMATION_REQUIRED`	202	Write tool first call: client must resubmit with the issued confirmation_token.
`SHROUD_CONFLICT`	409	Request conflicts with current resource state.
`SHROUD_CU_LIMIT_EXCEEDED`	429	Workspace credit-unit limit exceeded for the current window.
`SHROUD_IDEMPOTENCY_KEY_MISMATCH`	422	Idempotency-Key reused with a different request payload.
`SHROUD_INTERNAL_ERROR`	500	An unexpected server error occurred.
`SHROUD_INVALID_IDEMPOTENCY_KEY`	400	Idempotency-Key header is invalid for this endpoint or session.
`SHROUD_INVALID_PARAMS`	400	Request parameters failed validation.
`SHROUD_NOT_FOUND`	404	Requested resource does not exist.
`SHROUD_PERMISSION_DENIED`	403	Caller lacks the required capability for this tool.
`SHROUD_RATE_LIMITED`	429	Per-key request rate exceeded; retry after the indicated interval.
`SHROUD_SCHEMA_VIOLATION`	400	Tool inputs failed JSON-Schema validation against the registered InputSchema.
`SHROUD_SERVICE_UNAVAILABLE`	503	Upstream dependency briefly unavailable; retry after the indicated interval.
`SHROUD_TOOL_EXECUTION_ERROR`	500	Tool implementation returned an error.
`SHROUD_TOOL_NOT_FOUND`	404	No tool registered under the requested name.
`SHROUD_UNAUTHORIZED`	401	Authentication credentials missing, malformed, or rejected.
`SHROUD_WRITE_IN_BATCH`	400	shroud_batch refused: at least one inner call targets a write tool.

Error reference — envelope shape, HTTP status table, transport-specific notes, Retry-After and request_id guidance.
Production guide — Error handling map — caller-side action map for every code.
Authentication — SHROUD_UNAUTHORIZED triggers and the Bearer header contract.
Billing — SHROUD_CU_LIMIT_EXCEEDED and the per-window scope distinction.

Last modified: 08 May 2026

Error codes

Related