Troubleshooting

Decision trees, symptom-to-fix recipes, and the diagnostics packet to send to support for the most common AACsearch incidents.

This hub is for the moment something stops working. Pick the symptom that matches what you are seeing — each page lists likely causes, the exact checks to run, the fix, and the diagnostics packet to attach if you need to escalate.

Pick a symptom

Symptom	Page
`401`, `403`, "missing bearer token", "invalid or revoked key"	Auth errors
`429`, `rate_limit_exceeded`, `quota_exceeded`	Rate limits & quota
Search returns `found: 0` for queries that should match	Empty results
Search responds in >500 ms or times out	Slow search
Widget script loaded but UI never appears	Widget not loading
Documents do not show up after `sync/full` or `sync/delta`	Ingest failures
Connector marked "offline" in dashboard, heartbeat failing	Connector sync
`quota_exceeded`, plan blocks, overage budget	Billing limits

Decision trees

"Search returns 401"

Is Authorization header present?
  ├─ no  → add `Authorization: Bearer ss_search_...`
  └─ yes → does prefix match operation?
            ├─ ss_connector_* on /api/search       → use ss_search_* or ss_scoped_*
            ├─ ss_search_* on /api/connectors/*    → use ss_connector_*
            └─ correct prefix → has the key been revoked / expired?
                                 ├─ check Search → API Keys → status
                                 └─ if scoped: decode payload, check exp

→ Full recipe: Auth errors

"Search returns 0 results"

Does the index exist for this org?
  ├─ no  → check `indexSlug` and that the key has access
  └─ yes → are documents indexed?
            ├─ no  → see [Ingest failures](/troubleshooting/ingest-failures)
            └─ yes → does the query match `queryBy` fields?
                      ├─ no  → add the field to `queryBy`
                      └─ yes → are filters too narrow?
                                 ├─ remove filterBy and retry
                                 └─ check for scoped-token AND-combined filter

→ Full recipe: Empty results

"Search is slow"

First request after deploy?
  ├─ yes → cold-start; warm with a no-op query
  └─ no  → check perPage
           ├─ &gt;100 → reduce
           └─ ≤100 → check filterBy complexity
                      ├─ complex (many ORs) → simplify or precompute facets
                      └─ simple → check upstream search engine health

→ Full recipe: Slow search

"Connector says offline"

Heartbeat returning 200?
  ├─ no  → check connector key, see [Auth errors](/troubleshooting/auth-errors)
  └─ yes → last `lastUsedAt` &lt; 5 min ago?
            ├─ yes → dashboard cache; refresh
            └─ no  → connector process not running; restart and check logs

→ Full recipe: Connector sync

"Quota exceeded"

Did monthly limit reset?
  ├─ no (early in month) → which plan are you on?
  │                         ├─ Free  → upgrade or wait for 1st of month
  │                         ├─ Paid  → enable wallet overage in Billing
  │                         └─ Ent.  → contact support for true-up
  └─ yes → quota counter desync; refresh and retry once

→ Full recipe: Billing limits

Diagnostics packet

When you open a support ticket, attach the following — it cuts resolution time roughly in half because we can reproduce without a back-and-forth.

Field	Where to find it
Organization ID	Dashboard URL: `/orgs/<organization_id>/...` or Settings → Organization
Index slug	Search → Indexes (the URL-safe identifier, not the display name)
Time of incident	UTC timestamp — copy from your monitoring or browser dev tools
Request ID	Response header `X-Request-Id` (also logged client-side by the SDK)
Connector ID	Connectors → list view, "ID" column (only for connector-related issues)
Sync job ID	Returned by `sync/full` or `sync/delta`; visible in Connectors → Jobs
Full error response	The JSON body, not just the status code — we need the `error` and `message` fields
What you expected vs what happened	One sentence each

Privacy note: the diagnostics packet contains only IDs and timestamps. Do not paste API keys, scoped tokens, or document contents into a ticket — we have full server-side access for the relevant org.

Escalation template

Copy and fill this in for support@aacsearch.com:

Subject: [<plan>] <symptom> — org <organization_id>

Organization ID: org_...
Index slug: products
Time (UTC): 2026-05-11T14:32:00Z
Request ID: req_...
Connector ID (if applicable): conn_...
Job ID (if applicable): job_...

Expected:
  <one sentence>

Observed:
  <one sentence>

Error response:
{
  "error": "...",
  "message": "..."
}

Steps already tried:
  - [link to the troubleshooting page you followed]
  - [other things you ruled out]

Errors and rate limits — full error code matrix
API keys — key types, scopes, rotation
Plans and limits — quota tiers and feature gates
DR recovery runbook — for service-wide outages

Troubleshooting

On this page