> ## 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>