Диагностика
Деревья решений, рецепты "симптом → решение" и пакет диагностики для отправки в поддержку — для самых частых инцидентов AACsearch.
Этот хаб — на тот момент, когда что-то перестаёт работать. Выберите симптом, который соответствует происходящему: на каждой странице перечислены вероятные причины, точные проверки, исправления и пакет диагностики, который нужно приложить к тикету в поддержку.
Выберите симптом
| Симптом | Страница |
|---|---|
401, 403, "missing bearer token", "invalid or revoked key" | Ошибки авторизации |
429, rate_limit_exceeded, quota_exceeded | Лимиты и квоты |
Поиск возвращает found: 0 для запросов, которые должны были сработать | Пустые результаты |
| Поиск отвечает дольше 500 мс или зависает | Медленный поиск |
| Скрипт виджета загружен, но интерфейс не появляется | Виджет не загружается |
Документы не появляются после sync/full или sync/delta | Ошибки загрузки данных |
| Коннектор показывается как "offline", heartbeat падает | Синхронизация коннектора |
quota_exceeded, блок по тарифу, бюджет перерасхода | Биллинговые лимиты |
Деревья решений
"Поиск возвращает 401"
Заголовок Authorization присутствует?
├─ нет → добавьте `Authorization: Bearer ss_search_...`
└─ да → префикс соответствует операции?
├─ ss_connector_* на /api/search → используйте ss_search_* или ss_scoped_*
├─ ss_search_* на /api/connectors/* → используйте ss_connector_*
└─ префикс верный → ключ не отозван / не истёк?
├─ Search → API Keys → проверить статус
└─ если scoped: декодируйте payload, проверьте exp→ Полный рецепт: Ошибки авторизации
"Поиск возвращает 0 результатов"
Индекс существует для этой организации?
├─ нет → проверьте `indexSlug` и доступы ключа
└─ да → документы загружены?
├─ нет → см. [Ошибки загрузки данных](/troubleshooting/ingest-failures)
└─ да → запрос совпадает с полями `queryBy`?
├─ нет → добавьте поле в `queryBy`
└─ да → фильтры слишком узкие?
├─ уберите filterBy и попробуйте снова
└─ проверьте AND-комбинированный фильтр scoped-токена→ Полный рецепт: Пустые результаты
"Поиск медленный"
Первый запрос после деплоя?
├─ да → холодный старт; разогрейте no-op запросом
└─ нет → проверьте perPage
├─ >100 → уменьшите
└─ ≤100 → проверьте сложность filterBy
├─ сложный (много OR) → упростите или предвычислите фасеты
└─ простой → проверьте здоровье движка поиска→ Полный рецепт: Медленный поиск
"Коннектор показывается offline"
Heartbeat возвращает 200?
├─ нет → проверьте connector key, см. [Ошибки авторизации](/troubleshooting/auth-errors)
└─ да → последний `lastUsedAt` < 5 мин назад?
├─ да → кэш дашборда; обновите страницу
└─ нет → процесс коннектора не запущен; перезапустите и проверьте логи→ Полный рецепт: Синхронизация коннектора
"Quota exceeded"
Месячный лимит сбросился?
├─ нет (начало месяца) → какой у вас тариф?
│ ├─ Free → перейдите на платный или ждите 1-го числа
│ ├─ Платный → включите wallet overage в Billing
│ └─ Ent. → свяжитесь с менеджером для пересчёта
└─ да → счётчик квоты рассинхронизирован; обновите и попробуйте снова→ Полный рецепт: Биллинговые лимиты
Пакет диагностики
Когда открываете тикет в поддержку — приложите следующее. Это сокращает время решения примерно вдвое, потому что мы можем воспроизвести проблему без переписки.
| Поле | Где взять |
|---|---|
| ID организации | URL дашборда: /orgs/<organization_id>/... или Settings → Organization |
| Slug индекса | Search → Indexes (URL-безопасный идентификатор, не отображаемое имя) |
| Время инцидента | UTC-таймстамп — скопируйте из мониторинга или dev tools браузера |
| Request ID | Заголовок ответа X-Request-Id (также логируется SDK на клиенте) |
| ID коннектора | Connectors → списочный вид, колонка "ID" (только для проблем с коннекторами) |
| ID задачи синхронизации | Возвращается sync/full или sync/delta; видно в Connectors → Jobs |
| Полный ответ с ошибкой | JSON-тело, не только код статуса — нужны поля error и message |
| Что вы ожидали и что увидели | По одному предложению на каждое |
О приватности: пакет диагностики содержит только идентификаторы и таймстампы. Не вставляйте API-ключи, scoped-токены или содержимое документов в тикет — у нас есть полный доступ к серверу для нужной организации.
Шаблон обращения
Скопируйте и заполните для отправки на support@aacsearch.com:
Тема: [<тариф>] <симптом> — org <organization_id>
ID организации: org_...
Slug индекса: products
Время (UTC): 2026-05-11T14:32:00Z
Request ID: req_...
ID коннектора (если применимо): conn_...
Job ID (если применимо): job_...
Ожидалось:
<одно предложение>
Получено:
<одно предложение>
Ответ с ошибкой:
{
"error": "...",
"message": "..."
}
Что уже пробовали:
- [ссылка на страницу диагностики, по которой шли]
- [другие исключённые варианты]Связанные страницы
- Ошибки и rate limits — полная матрица кодов ошибок
- API-ключи — типы ключей, scope, ротация
- Тарифы и лимиты — уровни квот и feature gates
- Runbook восстановления при катастрофе — для service-wide отказов