Errors

One error shape, a named code for every failure, and a docs link in each.

Every error, on every endpoint, is the same shape:

{
  "error": {
    "code": "account_not_funded",
    "message": "The venue account 0x7e15…51f9 holds $0.00; this venue requires at least $5 to start.",
    "docs_url": "https://docs.superior.trade/runtime/credentials",
    "details": null
  }
}

• code — stable, machine-readable, never reworded. Branch on this.
• message — human-readable, specific to the instance (real values, not placeholders).
• docs_url — the page that explains the fix. Agents: fetch it as markdown via /<path>.md.
• details — structured extras where they exist (validation line numbers, coverage windows).

Every response — success or error — also carries an x-request-id header. Quote it in any support conversation; it's how we find your exact request in our logs.

Code registry#

Design commitments#

1. Distinct problems get distinct codes. "Not onboarded" is not "not funded"; an agent must be able to pick the right fix without parsing prose. (This is a direct lesson from the current API, where a missing agent wallet surfaced as a funding error.)
2. Codes are append-only. New failure modes add codes; existing codes never change meaning.
3. 5xx means us, 4xx means the request. A venue rejecting your key is a 4xx (credentials_invalid) — it's actionable by you. Our cluster being unreachable is a 5xx — retry later, we're paging someone.
4. Creates are retry-safe; money movement demands it. POST /runtime/deployments and /runtime/backtests accept an Idempotency-Key; /runtime/executions and /wallet/withdraw require it. Execution replays return the durable completed order record.
5. Destructive overrides are never a query flag. Deleting around open positions takes an explicit body acknowledgement (force + acknowledge_positions_open) — never a query flag.