> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplefunctions.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors reference

> Every error code SimpleFunctions emits — auth, validation, trade execution, upstream, internal — with status and fix path.

Errors come in two flavors: **CLI envelope errors** (when `--json` is set) and **HTTP errors** (status code + JSON body).

## CLI error envelope

```json theme={null}
{
  "ok": false,
  "command": "portfolio.history",
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "...",
    "status": 401,
    "details": {}
  },
  "meta": { "fetchedAt": "..." }
}
```

## Error codes

### Auth and access

| Code | Status | Meaning |
| - | - | - |
| `AUTH_REQUIRED` | 401 | No API key supplied |
| `AUTH_INVALID` | 401 | API key is invalid or expired |
| `AUTH_FORBIDDEN` | 403 | Key lacks the required scope |
| `RATE_LIMITED` | 429 | Per-key or per-route limit exceeded |
| `IP_BLOCKED` | 403 | IP-level block (rare) |

### Validation

| Code | Status | Meaning |
| - | - | - |
| `VALIDATION_ERROR` | 400 | Bad input (missing field, wrong type) |
| `UNSUPPORTED_OPERATION` | 400 | Operation not supported for this resource |
| `CONFLICT` | 409 | State conflict (e.g. publish a thesis with a duplicate slug) |

### Trade execution

| Code | Status | Meaning |
| - | - | - |
| `RISK_GATE_FAIL` | 403 | One or more risk gates blocked the order |
| `STALE_PRICE` | 400 | Specified price no longer reachable |
| `INSUFFICIENT_BALANCE` | 400 | Balance below required amount |
| `CATEGORY_BLOCKED` | 400 | Market category in your exclude list |
| `THESIS_MISMATCH` | 400 | Intent direction conflicts with linked thesis |
| `EXCHANGE_REJECT` | 502 | Kalshi or Polymarket rejected the order |
| `EXECUTION_HALTED` | 403 | `execution_mode` is `halted` |
| `DRY_RUN` | 200 | Order accepted as dry-run; no real execution |

### Resources

| Code | Status | Meaning |
| - | - | - |
| `NOT_FOUND` | 404 | Resource does not exist or is not visible to you |
| `GONE` | 410 | Resource was deleted |
| `EXPIRED` | 410 | Market expired and is settled |

### Upstream

| Code | Status | Meaning |
| - | - | - |
| `UPSTREAM_UNAVAILABLE` | 502 | Kalshi / Polymarket / mirror down |
| `UPSTREAM_TIMEOUT` | 504 | Upstream request timed out |
| `MIRROR_STALE` | 503 | Mirror data is too old to serve |

### Internal

| Code | Status | Meaning |
| - | - | - |
| `INTERNAL_ERROR` | 500 | Unhandled server error (logged with trace\_id) |
| `DATABASE_ERROR` | 503 | Postgres unavailable |
| `LLM_FAILURE` | 503 | OpenRouter / Anthropic provider failure |

## How to debug

<Steps>
  <Step title="Capture the full error">
    `--json` always returns the full error envelope.
  </Step>

  <Step title="Note the trace id">
    `details.traceId` is the audit chain key.
  </Step>

  <Step title="Share the trace id with support">
    Include `details.traceId` in any support email or issue. SimpleFunctions can correlate it back to the originating request, monitor cycle, or portfolio tick.
  </Step>

  <Step title="Inspect risk gates">
    For `RISK_GATE_FAIL`, `details.blocked` lists the specific gate(s).
  </Step>
</Steps>

## See also

<CardGroup cols={2}>
  <Card title="JSON contract" href="/cli/json-contract">
    Exit codes and CLI envelope shape.
  </Card>

  <Card title="Risk gates" href="/concepts/risk-gates">
    Why entry orders fail.
  </Card>

  <Card title="Provenance" href="/concepts/provenance">
    `traceId` audit chain lookup.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.