Errors and limits

Transport and authentication

Result	Meaning and handling
HTTP 401	Missing, expired or revoked access token. Follow WWW-Authenticate, refresh if possible, otherwise reconnect.
HTTP 405	An authenticated GET or DELETE was sent. Use POST; there is no standalone stream or session to delete.
HTTP 429	An endpoint rate limit was reached. Back off; use Retry-After when present.
Network failure or HTTP 5xx	The request could not complete reliably. Retry reads with backoff; avoid blind replay of actions.

An unauthorized request is rejected before method validation. A browser GET without a token can therefore return 401 rather than 405.

OAuth endpoints use OAuth errors such as invalid_grant and invalid_client_metadata. Token responses are not cacheable. If a refresh is refused because the grant is revoked or invalid, start a fresh authorization flow.

Tool failures

An MCP tool failure is returned as a tool result with isError: true and an explanatory text content block. It is not necessarily an HTTP failure. Inspect the MCP result before reading it as successful structured data.

Common refusals include:

• A project does not exist or is not accessible to the account. Both look like “Project not found.”
• Arguments are invalid or a required ID is missing.
• A conversation is already running or waiting for the person.
• The account's plan has ended or it has insufficient credits.
• No experiment is waiting for Start, or no step has failed to skip.

Show the error and a concrete next action. A refusal must not become a fabricated answer or a claim that work completed.

Permissions

Use IDs returned by list_projects. Reading answers and experiment status requires view access; asking, starting experiments and skipping steps require ownership. A connected administrator receives no special access to other people's projects.

Credits and real-world actions

ask_holyshift, create_project and experiments can spend credits. Check the balance before a batch of new work, but treat each action's result as authoritative: a previous balance does not reserve credits.

start_experiment and skip_failed_step should only be called when the person asked. Review the experiment plan before starting. Some agent actions can publish or send messages, subject to HolyShift's approvals.

There is no idempotency key for mutating MCP tools. If an action's response is lost, inspect the project or conversation before retrying; a new ask_holyshift without conversation_id can create duplicate work.

Current limits

• MCP HTTP request bodies are capped at 4 MiB.
• Questions are 1–20,000 characters.
• New-project descriptions are capped at 2,000 characters.
• list_experiments returns at most 20 experiments, newest first, without pagination.
• Conversation answers are polled; the MCP tasks extension is not supported.
• File downloads, resources, prompts, approval answers, experiment cancellation and failed-step retry are not exposed as MCP tools.

Call tools/list for the current input schemas and annotations. Tool names and schema fields are the integration contract; free-text descriptions and next messages are guidance for a person or model, not stable values to branch on.