Docs / Error codes

Error codes

Canonical API errors and what to do. Keep these behaviors stable.

Most common errors

missing_auth

You called an embed endpoint without an embed token header. Add x-microapp-embed-token: mtok_….

invalid_token

Token is invalid/revoked, or sent in an unsupported place (e.g. query string). Rotate/create a new mtok_… and send it via header / postMessage.

spec_not_allowed_for_public

You tried to make a tool public (Visibility: Public / Public runs ON) while its spec includes custom code execution (function steps / runtime.functions). Public tools cannot go live with custom code execution.

Option A

Set visibility to Private (turn Public runs OFF). Recommended for tools with custom code.

Next: Channels → Public app → Public runs OFF, then publish / set live again.

Option B

Replace function steps / runtime.functions with built-in deterministic runtime steps, then go live.

Option C

Keep it non-public and share via Embed tokens (mtok_…) for selected sites/apps.

Next: Use /schema?embed=1 and /run?embed=1 with header x-microapp-embed-token.

Typically returned as HTTP 409 during publish/go-live or set-live actions.

byok_required

The tool requires an LLM step, but the owner has no active AI key configured. Must be side-effect-free (no run logs, no quota charge, no token touch).

quota_exceeded

The owner hit plan quota (runs / AI actions / etc.). Upgrade plan or wait for quota window reset.

rate_limited

Too many runs in a short window. Back off and retry later. (HTTP 429)

llm_error

LLM provider failure during a run. The run is logged as failure, and quotas should be refunded.

Rule: Token is never accepted via query string. Don’t put tokens in iframe URLs.

Reproduce & debug quickly

Missing auth (no header)

# Missing auth (no token header)
curl -i "https://YOUR_MICROAPP_HOST/api/tools/YOUR_SLUG/schema?embed=1"

Invalid token (bad header value)

# Invalid token
curl -i "https://YOUR_MICROAPP_HOST/api/tools/YOUR_SLUG/schema?embed=1" \
  -H "x-microapp-embed-token: mtok_YOUR_TOKEN_BAD"

Valid run shape (embed=1 + header)

# Valid embed run (token via header)
curl -i "https://YOUR_MICROAPP_HOST/api/tools/YOUR_SLUG/run?embed=1" \
  -H "content-type: application/json" \
  -H "x-microapp-embed-token: mtok_YOUR_TOKEN" \
  --data '{"input":{"q":"hello"}}'

Windows PowerShell (curl.exe)

# Windows PowerShell (curl.exe) — pipe JSON via stdin (reliable)
$BASE = "https://YOUR_MICROAPP_HOST"
$SLUG = "YOUR_SLUG"
$MTOK = "mtok_YOUR_TOKEN"

'{"input":{"q":"hello"}}' | curl.exe -sS -i -X POST "$BASE/api/tools/$SLUG/run?embed=1" `
  -H "content-type: application/json" `
  -H "accept: application/json" `
  -H "x-microapp-embed-token: $MTOK" `
  --data-binary '@-'

spec_not_allowed_for_public (publish/go live)

# spec_not_allowed_for_public (owner-only)
# Happens when trying to publish/go-live while Visibility is Public (Public runs ON)
# and the spec includes custom code execution (function steps / runtime.functions).
curl -i -X POST "https://YOUR_MICROAPP_HOST/api/tools/YOUR_SLUG/draft/publish" \
  -H "authorization: Bearer mk_YOUR_OWNER_KEY" \
  -H "content-type: application/json" \
  --data '{"version":1,"makeLive":true,"note":"Go live"}'

# spec_not_allowed_for_public (owner-only)
# Happens when switching LIVE to a production version that includes custom code execution
# while Visibility is Public (Public runs ON).
curl -i -X POST "https://YOUR_MICROAPP_HOST/api/tools/YOUR_SLUG/production/set-live" \
  -H "authorization: Bearer mk_YOUR_OWNER_KEY" \
  -H "content-type: application/json" \
  --data '{"live":true,"version":3}'

Embed reminder (postMessage)

// Host-side reminder:
// Token must NOT be in the iframe URL.
// Send token via postMessage after the iframe says READY.

const iframe = document.getElementById("microapp");

window.addEventListener("message", (ev) => {
  if (!iframe || ev.source !== iframe.contentWindow) return;

  const data = ev.data || {};
  if (data.type === "MICROAPP_EMBED_READY") {
    iframe.contentWindow.postMessage(
      { type: "MICROAPP_EMBED_INIT", slug: "YOUR_SLUG", token: "mtok_YOUR_TOKEN", config: { locale: "en-US" } },
      ev.origin
    );
  }
});