Skip to main content
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 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
  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 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 — 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 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 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, 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
  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 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