Errors, limits & headers

The platform has two error envelopes. The execution planes (tools, agents, workflows, MCP, discovery, traces) use the router envelope; the models plane (/v1/chat/completions, /v1/embeddings, /v1/models) uses the OpenAI-shaped envelope from the inference gateway. Branch on the HTTP status and, on the execution planes, the X-Error-Code header — not on any field's type.

13.1 The two envelopes

Execution planes (orchestration/api-gateway/lib/respond.ts, lib/format.ts):

{ "error": { "code": "unknown_agent", "message": "No such agent: foo", "…": "extra fields" } }

• Header X-Error-Code: <code> is always set — clients can branch on it without parsing the body.
• Header x-request-id echoes the server-minted id.
• The body is format-negotiated: ?format= / body.format / Accept / a text/yaml content-type mirror select json (default), yaml, markdown, or text. An unknown explicit format → 400 invalid_format (as JSON). code+message survive every format; missing, contract, hint/detail, outcome and the execution id render on markdown (the MCP renderer) and missing on text; every field survives json/yaml.

Models plane (inference/gateway/src/errors.ts) — OpenAI shape, no X-Error-Code:

{ "error": { "message": "Invalid API key", "type": "authentication_error", "code": "invalid_api_key", "request_id": "…" } }

• code is a string, type groups it, request_id is inside the body. Response headers carry x-request-id (and x-correlation-id when you sent an x-request-id), never X-Error-Code.
• A known path called with the wrong method (GET /v1/chat/completions, POST /v1/models) answers 405 method_not_allowed with an Allow header naming the one method it serves:

13.2 Execution-plane error codes

13.3 Outcome → HTTP mapping

Execute routes classify an agent/tool outcome (routes/_util.ts outcomeStatus). A success: false engine result tagged with an outcome remaps to a caller-actionable status; an untagged failure stays 502 engine_error.

13.4 Rate limits

Execution planes (orchestration/mcp-gateway/rate-limiter.ts, a Durable Object; enforced in lib/auth.ts). Counted on POST executions only — catalog GETs are free. Per tier:

A key with no tier is treated as free. A per-key rate_limit override is ignored on these planes (lib/auth.ts does not pass it to checkRateLimit); it applies only on https://mcp.plungeai.com/v1. Failed authentications are metered per client IP (auth-fail: 20/min, 500/day) to bound key brute-force. On a limit hit: 429 rate_limited with a Retry-After header (seconds). A key is never shut out for longer than ten minutes: reaching the day limit pauses the key for 10 minutes (Retry-After ≤ 600), after which its day count starts over (2026-10-05; the minute limit waits out the minute as before). The per-tier numbers are the defaults: the operator can change them or switch the limits off (the failed-authentication meter stays on), see 2.

Money plane (inference/gateway/src/auth/rate-limit.ts). Per key, atomic per-minute window (RateLimiterDO, KV soft-cap fallback): default 600 req/min (RATE_LIMIT_RPM_DEFAULT) → 429 rate_limit_exceeded. Separate from billing caps: 429 insufficient_quota (monthly limit / trial allowance), 402 insufficient_balance (empty wallet), 429 spend_cap_exceeded (guardrail) — see 3.10, 3.13.

13.5 Trust fence

Two statuses gate risky actions:

• 403 refused — the agent/tool refused the action outright (policy). Do not retry unchanged.
• 409 approval_required — a human must approve before the action runs. Approve out-of-band, then re-issue the request.

13.6 Limits: body caps, timeouts

• Body cap (execution planes): MAX_REQUEST_SIZE, default 1 MiB (routes/_util.ts — 1_048_576 bytes). Enforced against Content-Length first, then streamed; over → 413 payload_too_large. The models plane relies on the provider/runtime body limits.
• Timeouts: there is no gateway-imposed request timeout beyond the Cloudflare Workers runtime and each upstream's own. Streams have no idle timeout on the money/workflows plane; the agents plane sends : OCEAN PROCESSING keepalives (4.3).
• Storage errors are scrubbed: a D1/SQLite failure surfaces as 502 upstream_error "storage error" (the raw error is logged, never leaked); internal service-binding names are redacted from messages.

13.7 Retry guidance

• 429 — back off and honour Retry-After. Distinguish rate_limited/rate_limit_exceeded (throttle) from insufficient_quota/spend_cap_exceeded (billing — retrying won't help until the window resets or billing changes).
• 5xx (502/503) — retry with exponential backoff; the models plane already retries 429/5xx once per candidate and fails over (3.3).
• 4xx other than 429 — do not retry unchanged; fix the request. needs_* outcomes (422/424) are yours to resolve (params, connection, key).
• Always include the x-request-id when reporting an error.

13.8 Response headers

13.9 Verified examples

Unauthenticated execution-plane request → 401 unauthorized with the x-error-code header:

curl -is "$API_BASE/v1/agents"

Unknown route → 404 not_found, header x-error-code: not_found, plus x-request-id:

curl -is "$API_BASE/v1/nope"

Agent execute without a prompt → 400 missing_prompt:

curl -s "$API_BASE/v1/agents/one-agent/execute" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

Unknown agent id → 404 unknown_agent (the trust/fence pre-dispatch check):

curl -s "$API_BASE/v1/agents/zzz-not-an-agent/execute" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H "Content-Type: application/json" -d '{"prompt":"hi"}'