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

# Troubleshooting

> Common errors during install, auth, rate limits, trading, webhooks, and CLI agent — with concrete fixes.

## Install

### `command not found: sf`

Your npm global bin isn't on PATH:

```bash theme={null}
npm config get prefix
# add the resulting path's /bin to your PATH
```

Install the current npm package:

```bash theme={null}
npm install -g @spfunctions/cli
```

## Auth

### `AUTH_INVALID` on every command

Your API key is wrong, expired, or revoked.

```bash theme={null}
sf status --json | jq '.auth'
sf login    # re-issue
```

### `AUTH_FORBIDDEN` on a specific command

The key works but lacks scope. Issue a new key with the right scopes — see [API keys](/enterprise/api-keys).

## Rate limits

### `RATE_LIMITED` on every call

Wait `Retry-After` seconds. Sustained rate limiting means you need a higher tier — see [Rate limits](/enterprise/rate-limits).

## Trading

### `RISK_GATE_FAIL`

`details.blocked[]` lists the gate(s). Common causes:

* Daily loss cap hit — wait until UTC day rolls.
* Total exposure cap — close positions or raise `max_total_exposure_cents`.
* Cooldown — wait the configured tick count.

See [Risk gates](/concepts/risk-gates).

### `EXECUTION_HALTED`

Your `execution_mode` is `halted`. Triggered automatically when drawdown breaches `max_drawdown_halt_cents`. Recover with:

```bash theme={null}
sf portfolio config executionMode live
```

(After verifying the halt was for the right reason.)

### `EXCHANGE_REJECT`

The venue rejected the order. The error message includes the venue's reason. Common: market closed, price out of range, position limit at venue.

## Webhooks

### Endpoint auto-paused

50%+ failure rate over 24h. Fix the receiver, then:

```bash theme={null}
sf webhooks resume <endpoint-id>
```

### Signature verification fails

Common pitfalls:

1. Receiver consumed the body before passing to verifier. Use raw body.
2. Receiver decoded JSON before verifying. Verify on the raw bytes.
3. Clock skew > 5 minutes. Sync your server time.
4. Wrong secret. Re-issue with `sf webhooks rotate-secret <id>`.

See [Webhook receiver](/integrations/webhook-receiver).

## CLI agent

### `Order cancelled (no confirmation)`

You're in a non-TTY environment (autopm, CI, scripted). Set:

```bash theme={null}
export SF_AUTO_CONFIRM=1
```

<Warning>
  Do not set `SF_AUTO_CONFIRM=1` in production unless you understand the implications. It bypasses interactive confirmation. Risk gates still run, but if any code path proceeds despite a gate failure (a bug), there's no human in the loop.
</Warning>

### Agent loops without acting

Check if `execution_mode` is `dry-run`. Agent will keep recommending without acting. Switch to `live` only after you trust the agent's behavior.

## See also

<CardGroup cols={2}>
  <Card title="Errors reference" href="/reference/errors">
    Every error code with status and fix path.
  </Card>

  <Card title="FAQ" href="/resources/faq">
    Frequently asked questions.
  </Card>

  <Card title="Status" href="/resources/status">
    Live system status and incident history.
  </Card>
</CardGroup>