Errors

All errors use one envelope:

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "must be a UUID",
    "details": { "field": "option_id" }
  }
}

code is the stable contract — branch on it, not on message wording. details is optional context (offending field, retry_after seconds, required_scope, …). Over MCP, errors arrive as tool errors whose text is CODE: message, so agents get the same signal and can branch on the same codes.

General codes

code	HTTP	When
`UNAUTHORIZED`	401	Missing, invalid, revoked, or expired key; or the key’s account is no longer active
`FORBIDDEN_SCOPE`	403	The key lacks the scope this operation needs — `details.required_scope` names it
`NOT_FOUND`	404	Resource doesn’t exist, or is hidden by privacy/moderation — existence is never leaked
`INVALID_ARGUMENT`	400	Parameter validation failed (`details.field` names it — e.g. `amount_coins` that is not a positive JSON integer, or an unknown `flow` / `source` on the ruby ledger)
`RATE_LIMITED`	429	Over quota — see Rate limits
`SERVICE_DISABLED`	503	The Open API is temporarily switched off (maintenance/emergency)
`INTERNAL`	500	Our bug — retry once, then back off

Confirm-token codes

Returned by the three execute operations. See Write actions and confirmation.

code	HTTP	When
`CONFIRM_TOKEN_INVALID`	400	Malformed or tampered with, or minted for a different user, key or action
`CONFIRM_TOKEN_EXPIRED`	409	Older than 5 minutes (or, for publishing, the staged text expired) — preview again
`CONFIRM_TOKEN_USED`	409	Already consumed. For `publish_opinion` this also covers reposting the same text within a minute
`CONFIRM_UNAVAILABLE`	500	Token signing is unavailable server-side — writes are refused rather than waved through

Write rule codes

Rejections that come from the rules of the action itself.

code	HTTP	When
`MECHANISM_UNSUPPORTED`	—	Preview `reason`: a legacy `v2_share` topic; only `v21_lmsr` is tradable here
`STAKE_OUT_OF_RANGE`	200 / 409	The stake is outside the topic’s `stake_rules`. On `preview_order` it is a `reason` (HTTP 200, `can_place: false`, `details.min_coins` / `details.max_coins`) — ask the user for an amount in range. On `place_order` (409) it is a safety mapping the normal flow never reaches
`TOPIC_ALREADY_STAKED`	409	This topic’s one order already exists — including one the user has since sold in the SeeSaw app. No adding, switching or re-entering
`TOPIC_CLOSED`	409	Trading closed between preview and execute
`TOPIC_QUOTE_EXPIRED` / `TOPIC_QUOTE_INVALID`	409 / 400	The price quote could not be honored
`INSUFFICIENT_BALANCE`	400	Not enough coins for the stake or backing price
`OPINION_NOT_FOUND`	404	The opinion (or reply target) doesn’t exist
`OPINION_SIDE_REQUIRED` / `OPINION_SIDE_INVALID`	400	`publish_opinion` only, and rare: the owner’s position changed between preview and execute so the previewed side no longer fits, or the side is not an option of the topic. `preview_opinion` reports a missing side as reason `SIDE_REQUIRED` instead
`OPINION_TOPIC_CLOSED` / `OPINION_TOPIC_HIDDEN`	403	The topic no longer accepts opinions
`OPINION_ALREADY_BACKED`	409	This user already backed the opinion — once per person
`OPINION_BACK_PRICE_MOVED`	409	The relay price rose above the confirmed cap — preview again
`OPINION_BACK_FULL`	409	The backing price ladder is exhausted
`CONTENT_INVALID`	400	Empty or over 500 characters
`CONTENT_MODERATED`	400	Rejected by moderation
`USER_PUNISHED`	403	The account is restricted from posting
`RETRY_IDEMPOTENCY_KEY`	409	A concurrent identical request is in flight — retry shortly
`OPINIONS_UNAVAILABLE`	503	Opinions are temporarily switched off

Real examples

401 — no key (captured live):

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Provide an API key: Authorization: Bearer sspat_…"
  }
}

401 responses carry a WWW-Authenticate: Bearer realm="seesaw-open-api" header. Depending on the network path it may arrive under the name x-amzn-remapped-www-authenticate — match either when debugging.

403 — read-only key on a write endpoint (captured live):

{
  "error": {
    "code": "FORBIDDEN_SCOPE",
    "message": "API key lacks the required scope: write",
    "details": {
      "required_scope": "write"
    }
  }
}

Scopes are fixed at creation — create a new key with the write scope rather than looking for an upgrade endpoint. See Authentication. 409 — reusing a spent token (captured live):

{
  "error": {
    "code": "CONFIRM_TOKEN_USED",
    "message": "This confirm_token was already used; run the preview again for a new one"
  }
}

400 — tampered token (captured live):

{
  "error": {
    "code": "CONFIRM_TOKEN_INVALID",
    "message": "The confirm_token is not valid for this key, user or action"
  }
}

429 — rate limited: see Rate limits for the full shape and headers.

404 semantics worth knowing

A 404 does not distinguish between “never existed”, “hidden by the owner’s privacy settings”, and “removed by moderation” — deliberately. Don’t retry 404s; surface them as “not available”.

Preview reasons are not errors

When a preview returns can_place / can_publish / can_back as false, the call succeeded (HTTP 200). The blocking condition is in reason and the summary still carries real numbers, so you can explain the situation to the user instead of reporting a failure. No confirm_token is issued.

Getting Started

Concepts

MCP Server

Platform

General codes

Confirm-token codes

Write rule codes

Real examples

404 semantics worth knowing

Preview reasons are not errors

​General codes

​Confirm-token codes

​Write rule codes

​Real examples

​404 semantics worth knowing

​Preview reasons are not errors

General codes

Confirm-token codes

Write rule codes

Real examples

404 semantics worth knowing

Preview reasons are not errors