PAMbaseDocs
Resources

Troubleshooting & FAQ.

The most common integration issues, what causes them, and the fix. Errors come back as { error: { code, message, details? } } — match on code (or the typed SDK error) rather than the message text.

Quick reference

Code / symptomCauseFix
401 unauthorizedToken expired or revoked (no refresh exists)Discard the token, re-run the connect flow
403 scope_deniedYou lack the scope, or requested a form the user didn't grantDeclare it in the manifest, re-consent; check wildcard form
Empty context / memoriesNew user, missing read scope, or wrong scope filterCheck listUserScopes(); confirm counts > 0
400 unknown scopeMemory write's top-level scope isn't a standard namespaceUse a standard namespace (or general); see the Catalog
402 limit_exceededPlan cap hitSee limits / upgrade plan
Webhook not arrivingNo active connection, missing read scope, or no subscriptionVerify all three; you're never self-notified
Bad-signature webhooksVerifying after parsing, or wrong/rotated secretVerify over the raw body with the current secret

401 unauthorized

The connection token is expired or revoked. There are no refresh tokens — the only recovery is re-running the connect flow. Catch UnauthorizedError, drop the stored token, and prompt the user to reconnect.

403 scope_denied

Your token doesn't carry the scope the call needs. Two things to check:

  • Manifest. The scope must be declared in your manifest and then approved by the user — re-consent if you added it after they connected.
  • Wildcard form. memory:read:schedule and memory:read:schedule.* aren't the same; schedule.calendar is matched by schedule.*, not by a bare schedule. The SDK error's .scope names what was denied.

Empty context or memories

Usually one of three things, in order of likelihood:

  1. The user is new and the store is genuinely empty for those scopes.
  2. You lack the read scope for the namespace you expected.
  3. You queried the wrong scope filter (e.g. asked for health when data is under fitness).
typescript
const { scopes } = await pambase.listUserScopes();
console.table(scopes); // [{ scope, count, standard }] — what you can actually read
// count === 0 everywhere → new user. Missing a namespace → scope/grant issue.
Discovery first
Make listUserScopes() your first diagnostic. It tells you what exists before you assume the read is broken.

400: memory write to an unknown scope

A memory write's top-level scope must be a standard namespace from the Catalog — an unknown namespace returns 400 with a pointer to the catalog. Sub-scopes under a standard namespace (e.g. finance.crypto) are free, and general always works. Signal types, by contrast, are free-form and never rejected.

402 limit_exceeded

You hit a plan cap (request volume, memory count, etc.). The response code is 402. Review your usage against Limits and upgrade if needed.

A memory write returns 400 (unknown scope)

A remember() write whose top-level scope namespace isn't in the standard taxonomy is rejected. Use a standard namespace (sub-scopes like fitness.running are free) or fall back to general. See Remember & recall.

Webhook isn't arriving

Check, in order:

  • Active connection. The user must currently have your app connected (not revoked).
  • Read scope covers the namespace. You're only notified within scopes you can read — fanout is gated like /v1/context.
  • An active subscription. A delivery URL must be registered (and its event-type/scope filters must match).
  • Not your own event. Apps are never self-notified — if your app emitted it, it won't come back.
  • Your endpoint acks 2xx within ~5s. Non-2xx/timeout is retried up to 6 times, then marked failed.

Webhook signature fails verification

Almost always one of: verifying after JSON parsing (verify the raw body), using a rotated/old secret, or a body transform by a proxy. See Webhooks and Security.

Embeddings / LLM offline in dev

Local dev may run without an embeddings or LLM backend. When that happens, semantic search degrades and unknown event types are stored raw with no memory candidates (the rule-based extractors still work). This is expected locally — see Testing & sandbox.

Related