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

# Troubleshooting

> Common errors when integrating PromptWall, and exactly how to fix each one.

If something isn't working, find the error symptom below and follow
the fix. If your symptom isn't here, email
[support@prompt-wall.com](mailto:support@prompt-wall.com) with the
`request_id` from the response — that gives us the full server-side
trace.

***

## Authentication errors

### `401 Unauthorized` — `{"code": "auth", "message": "Invalid API key"}`

**Cause:** the `pk_live_…` key in your request is wrong, revoked, or
not yet propagated.

**Fix:**

1. Open [Settings → Apps](https://www.prompt-wall.com/settings)
2. Find the app you're using
3. Click **Rotate key** if you suspect compromise, or **Reveal key** to
   confirm what's installed
4. Set the value in your env (`PROMPTWALL_API_KEY` or whatever your
   wrapper uses)
5. **Restart your app** — env changes don't propagate until restart

### `401 Unauthorized` — `{"code": "auth", "message": "Mode not allowed for this key"}`

**Cause:** your key is provisioned for **Events**, but you're calling
`/v1/verify` or `/v1/chat`.

**Fix:** in [Settings → Apps](https://www.prompt-wall.com/settings)
either:

* Edit the app and change **Mode** to Verify or Full Control (key
  stays the same), **or**
* Provision a new app with the wider mode and use that key

Verify is a strict superset of Events — a Verify-mode key can call
both. Full Control is a strict superset of Verify.

### `403 Forbidden` — `{"code": "auth", "message": "Org suspended"}`

**Cause:** payment failure or contract expiry.

**Fix:** open
[prompt-wall.com/billing](https://www.prompt-wall.com/billing) — there
will be a banner with the exact reason and a "Resolve" CTA.

***

## Quota / rate-limit errors

### `429 Too Many Requests` — `{"code": "rate_limit", "message": "Per-minute rate exceeded"}`

**Cause:** your app burst over the per-minute soft cap (default
300 RPM per app).

**Fix:**

1. Implement exponential backoff with jitter — start with the
   `Retry-After` header value
2. Open [Settings → Apps → your app → Rate limits](https://www.prompt-wall.com/settings)
   and raise the cap if you legitimately need more
3. If you're seeing bursts from a runaway client, throttle on **your**
   side first — it's cheaper than raising the cap

### `429 Too Many Requests` — `{"code": "quota", "message": "Credit pool exhausted"}`

**Cause:** you've consumed your USD-credit pool and overage is
disabled.

**Fix:** top up at
[prompt-wall.com/billing](https://www.prompt-wall.com/billing) or
enable overage on your contract.

***

## Latency / timeout

### `/v1/verify` is taking 800 ms+ p95

**Likely cause:** you're sending very long `answer` payloads (>4000
tokens) or you have many active policies that perform regex /
embedding scans.

**Fix:**

1. Trim the `answer` to what's actually user-facing — system tokens
   and tool scaffolding don't need verification
2. In [Settings → Policies](https://www.prompt-wall.com/policies),
   disable any policies you don't actually rely on — every policy adds
   \~5–20 ms

### `/v1/chat` timing out at 30 s

**Likely cause:** the upstream LLM is slow (Claude long-context can
take 25 s+) or your `max_tokens` is set very high.

**Fix:**

1. Raise the SDK timeout (`PromptWall(timeout=60)` in Python or
   `timeoutMs: 60_000` in Node)
2. Cap `max_tokens` to what your UI can actually display
3. Consider streaming (`stream: true`) — your user sees tokens as they
   arrive instead of staring at a loading spinner

***

## Wrong / unexpected responses

### Verify always returns `governance: allow` even on obvious bad answers

**Likely cause:** no policies are active, or the active policies are
in `inactive` / `testing` status.

**Fix:**

1. Open [Settings → Policies](https://www.prompt-wall.com/policies)
2. Find the policy you expected to fire (e.g.
   `security.prompt_injection`)
3. Confirm **Status = Active** and **Action ≠ allow**
4. Check the **App** scope — if a policy is scoped to a specific app
   and your call is using a different app's key, the policy won't fire

### Full Control returns the original answer on a `rewrite` decision

**Likely cause:** your client code is reading `answer` directly without
checking `governance`.

**Fix:** `result.answer` is always the **safe-to-show** text — when
`governance == "rewrite"`, `answer` already contains the rewritten
version. Don't pull from `result.original_answer` unless you actually
want the un-rewritten original (it's there for audit, not display).

### Traces missing from /observability

**Likely cause 1:** events are still propagating (5 s lag is normal).

**Cause 2:** you're filtering /observability to a different App than
the key you're sending with. The default time filter is "last 24h" —
old events won't show.

**Fix:**

1. Wait 30 seconds, refresh
2. Clear all filters in /observability and re-check
3. Look at the response from PromptWall — does it return a
   `request_id`? If yes, the request reached us. Search by request\_id
   in /traces. If no, your client never reached the API (firewall,
   proxy, DNS).

***

## SDK-specific errors

### Python: `ImportError: cannot import name 'PromptWall' from 'promptwall'`

**Likely cause:** ancient SDK version or local module shadow
(`promptwall.py` in your project root).

**Fix:**

1. `pip install --upgrade promptwall`
2. Confirm `python -c "import promptwall; print(promptwall.__file__)"`
   points to site-packages, not your local file
3. If you have a local `promptwall.py`, rename it

### Node.js: `Module not found: '@promptwall/node'`

**Likely cause:** you installed the wrong package.

**Fix:** the SDK is published as `@promptwall/node`, not `promptwall`.
`npm install @promptwall/node`.

### Node.js: `fetch is not defined` on Node 16

**Cause:** the SDK uses native `fetch`, only available on Node 18+.

**Fix:** upgrade to Node 18 LTS or later. We do not support Node 16.

***

## Network / infrastructure

### `ECONNREFUSED` on `api.prompt-wall.com`

**Likely cause:** corporate firewall blocking outbound HTTPS to
`api.prompt-wall.com`.

**Fix:** allowlist the following:

* Hostname: `api.prompt-wall.com`
* Port: 443 (HTTPS)
* Optional: pin the cert SHA via `https://api.prompt-wall.com/.well-known/cert.json`

For air-gapped deployments contact
[support@prompt-wall.com](mailto:support@prompt-wall.com) about a
self-hosted edition.

### TLS handshake failures

**Likely cause:** outdated CA bundle on the client.

**Fix:**

* Python: `pip install --upgrade certifi`
* Node: upgrade to a current LTS
* cURL: `--ca-bundle` to a recent bundle

***

## Where to get help

* **Email:** [support@prompt-wall.com](mailto:support@prompt-wall.com)
  — include `request_id` if you have one
* **Status page:** [status.prompt-wall.com](https://status.prompt-wall.com)
  — check before opening a ticket if everything just stopped working
* **Slack** (Enterprise): your dedicated channel