Errors, feedback & limits

Source: orchestration/mcp-gateway/tool-outcome.ts, server.ts (wrap, validateToolArgs), index.ts, shared.ts, auth-middleware.ts, rate-limiter.ts, session-do.ts, resources.ts, prompts.ts, tools.ts, tool-exec.ts, extras.ts, activity-log.ts, log-view.ts, execution-do.ts, leg-state.ts, core/core-base/content-guard.ts, orchestration/api-gateway/lib/auth.ts, MCP SDK 1.29.0, live registry cards (2026-09-24).

When something cannot run, the platform does not just fail. It answers with what is missing and how to fix it. Your client reads that answer and usually corrects itself. This chapter is so that you know what is happening: the answer shapes, every error code, the limits, when to retry, and how to read your own activity log. It applies to https://mcp.plungeai.com/v1. The same server at https://api.plungeai.com/v1/mcp differs only at the edge (4.11).

13.1 Three kinds of "no"

Your request
 ├─ stopped at the edge: auth, size, rate limit, parse,          → JSON-RPC error + HTTP status (13.6)
 │   unknown or fenced tool, unknown method/resource/prompt          nothing ran
 ├─ reached a tool that answered with guidance                   → a result with an outcome (13.2)
 │   needs_input / needs_connection / needs_api_key /                usually nothing ran
 │   needs_approval / unavailable / error
 └─ reached a tool that answered with a plain failure            → a result, isError: true, text only (13.5)

A client should branch in this order: first the HTTP status and the JSON-RPC error, then result.isError, then result.structuredContent.status.

13.2 The structured-feedback contract

The six tools whose outputSchema is the outcome envelope never answer with a bare error: plungeai_execute_workflow, plungeai_execute_agent, plungeai_execute_tool, plungeai_get_tool_contract, plungeai_run_mission and plungeai_learn (4.9). Every answer carries an outcome: a status plus a summary, and usually a remediation saying exactly what to do. plungeai_get_result uses the same envelope for its guidance answers (a missing or unknown id). A paused run is not an envelope there: its result text ends with a ⏸ block, and format:"json" gives {"content": …} with no status. For machine-readable pause state, read structuredContent.continuation from plungeai_get_workflow_status (9.3). Two paths hold the promise for every tool: argument validation (13.3) and unexpected exceptions (13.4).

Every non-ok answer ends with the line _This is structured guidance, not a crash — do not retry the identical call. Follow the remediation, or relay it to the user._

The envelope is the structuredContent object: status, summary, agent_id, operation, result, execution_id, missing[], warnings[], remediation { message, actions[] } and contract (field reference in 4.9). The Markdown text shows the same information as a status line, the summary, Missing required: …, **To proceed:** <message> and one bullet per action. Each warning becomes a ⚠️ line.

Remediation actions (RemediationAction), and how each is rendered for your client:

Connection and key remediations point at Ocean Studio, https://studio.plungeai.com → Connectors.

A refusal is not a run. If the platform stops a call before dispatch (a missing field, a missing connection, an unknown or inactive agent, an unknown model), no execution is created. Nothing half-happens, and your history stays clean. Looking up a result by an id that does not exist gets a needs_input answer naming the id (plungeai_get_result), never a bare "not found".

Limits are told to you, never silently applied. Search engines declare their maximum query length on their card (live-verified 2026-09-24): serper-agent 2,048 characters, brave-agent 400, tavily-agent 400. Send more and you get needs_input with the limit. Your input is never truncated behind your back.

The real reason comes back. When a run fails, the classifier (classifyExecutionError) passes the upstream reason through: Execution failed: <reason>, The run timed out: <reason>, or the agent's own message on unavailable. You do not get a generic "something went wrong".

Visible mapping, never guessing. Send only prose to plungeai_execute_tool for an agent whose form has exactly one required free-text field (a report generator's content, say), and the platform fills that field with your prose and says so: ⚠️ prose mapped: your prompt was passed as `content` (this card's only required parameter)…. Details are in Tools.

13.3 Argument validation

Every tools/call is checked against the tool's input schema before the tool runs (server.ts validateToolArgs, called from index.ts). A failure is not a protocol error. It is a needs_input outcome, returned as a normal JSON-RPC result (HTTP 200, plain JSON):

• summary: `plungeai_list_agents` was not called — its arguments do not match the tool's schema. followed by one `field`: message per problem;
• missing[]: required fields that were absent;
• remediation.actions: one provide_field per missing or bad field.

Nothing runs, but the call still counts toward your rate limit. Free to try:

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_list_agents","arguments":{"user_request":"list agents","limit":500}}}'

The bounds every tool shares (shared.ts, tools.ts). Per-tool parameters are in the Tool reference.

This pre-screen covers single-message requests. Inside a JSON-RPC batch, bad arguments come back as the SDK's own isError text (Input validation error: …) instead (4.4).

13.4 Transient failures

If a tool throws unexpectedly (a database hiccup, a service-binding blip), the server still answers with an outcome (server.ts wrap):

• status: "error", isError: true;
• summary: the error message and (request <request id>). Messages that would expose internals (database or parser errors) are replaced with An internal error occurred while running this tool.;
• remediation.message: This is a transient platform failure, not a bad request. Retry once in a few seconds; if it persists, report the request id above.

format: "json" is honoured on this path too. The full error goes to the server logs under the same request id.

13.5 Plain tool errors

Tools without an outputSchema answer their own failures as a plain text result with isError: true and no structuredContent. Examples from the code:

They are short and say what to do. Treat them like a needs_input or error outcome.

13.6 JSON-RPC and HTTP errors

Protocol errors mean the request never reached a tool. The body is always {"jsonrpc":"2.0","error":{"code":…,"message":"…"},"id":…}. id is null when the server had not parsed one.

Unauthenticated requests, live-verified 2026-09-24:

curl -s -i -X POST https://mcp.plungeai.com/v1 -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

curl -s -i -X POST https://mcp.plungeai.com/v1 -H 'Authorization: Bearer not-a-key' \
  -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

An unknown tool is a protocol error, so it cannot be mistaken for "the tool ran and failed":

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"plungeai_nope","arguments":{}}}'

On https://api.plungeai.com/v1/mcp, the router answers its own edge errors in the One API envelope: 401 unauthorized (Bearer ozk_ key required / Invalid or revoked API key), 429 rate_limited, 413 payload_too_large, each with X-Error-Code (One API errors (opens in a new tab)). Everything the MCP server answers passes through unchanged.

13.7 Rate limits

Your key's tier sets two fixed windows, per minute and per day (rate-limiter.ts):

• Only tool calls count. initialize, tools/list, resources/*, prompts/* and ping are free on https://mcp.plungeai.com/v1 and on https://api.plungeai.com/v1/mcp, which forwards your key to the same gateway (4.11).
• The counter is per account (your user id), not per key. Two keys on one account share it.
• Windows are fixed, not calendar-aligned. A window starts at the first counted call after the previous one ended and lasts 60 seconds (or 24 hours).
• A key with a missing tier is treated as free. An operator can give a key its own per-minute limit, which replaces the tier's per-minute number (the daily limit stays). Self-service keys use the tier limits.
• Failed logins are counted per client IP: 20 per minute and 500 per day. After that the server answers 429 Too many failed authentication attempts until the window resets.

On a limit hit you get 429 with Retry-After (seconds until the window resets, at least 1) and error.data.retryAfter, and the call does not run. Ask "how much of my rate limit have I used?": plungeai_whoami shows minute_used and day_used for the current windows. Its own call counts, so the number includes it.

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"plungeai_whoami","arguments":{"user_request":"how much of my rate limit have I used?"}}}' \
  | sed -n 's/^data: //p'

These limits bound request rates. Spending (model tokens, paid APIs) is metered separately on your account, and money-moving actions stop at the trust fence (Tools).

13.8 Body caps and timeouts

The server itself sets no request timeout on a tools/call. Your client may: Claude Desktop cuts a single tool call at about 4 minutes (server.ts). Claude Code lets you set a per-server timeout (milliseconds) in .mcp.json, or MCP_TOOL_TIMEOUT (Claude Code docs (opens in a new tab), read 2026-09-24). For anything long, use mode: "async" (4.7).

13.9 Retry guidance

13.10 The activity log

The server keeps a readable trail of everything your account did over MCP: one Markdown entry per request, grouped per account per UTC day (activity-log.ts, log-view.ts). Use it to see exactly what your client sent, which is often not what you typed, and what came back.

Read it with your own key. It is assembled live on every request, newest first:

curl -s "https://mcp.plungeai.com/log?date=$(date -u +%F)" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"

The same handler also answers at /admin/log. Responses are Cache-Control: no-store. A key reads only its own account's trail. A missing or wrong key gets 401 {"error":"Provide your API key: Authorization: Bearer <key>, X-API-Key, or ?key="}. The log is served on https://mcp.plungeai.com only.

What an entry looks like (the shape activity-log.ts renders):

### 14:03:12 · `plungeai_whoami` · ✅ · 212ms
- **User:** you@example.com · <your user id> · <client IP> · `<request id>`
- **Key:** <key label>

> **Asked:** how much of my rate limit have I used?

**Q:**
- **format:** markdown

- **A:** <the answer, whole if 300 characters or fewer, else "<n> chars · <first 240 characters>…">

What is recorded. Every authenticated request: tool calls, argument rejections, rate-limit hits, fenced-tool denials and protocol methods. Failed logins are recorded without an account, so they do not appear in your log. Secrets are redacted before anything is written: the value of any argument whose name looks like a secret (api_key, api_secret, token, secret, password, passwd, credential, authorization, cookie) is stored as •••redacted•••, including everything nested under it (core/core-base/content-guard.ts). A secret pasted into free text, such as a prompt, is not detected. Don't paste keys into prompts.