Дерево решений по типичным сбоям AACsearch до открытия тикета.

Troubleshooting

Большинство продакшн-проблем укладывается в 7 паттернов. Это дерево: идите сверху, на совпадающий вопрос — лист с фиксом или с пометкой «реально к саппорту с уже собранной диагностикой».

Эскалация после этой страницы — Эскалация саппорту.

Дерево

Неожиданные результаты поиска?               → «Неправильные результаты»
4xx от поиска?                               → «Auth / origin / rate-limit»
5xx от поиска?                               → «Server-side errors»
Ingest не доходит до поиска?                 → «Устаревшие или отсутствующие документы»
Документы приходят, потом исчезают?          → «Документы исчезают»
Реиндекс завис или упал?                     → «Проблемы реиндекса»
Дашборд тормозит/неправильные цифры?         → «Проблемы дашборда»

Неправильные результаты

Симптом	Самая вероятная причина
«Искал X — ничего»	Typo tolerance выключен или поле не в `query_by`.
«Не возвращает свежий документ»	Документ в буфере, ещё не флашнули. Diagnostics.
«В выдаче удалённый вчера документ»	Delete в буфере не флашнут; идёт реиндекс; или delete по одному документу, а приложение ищет в soft-delete-вьюхе.
«Не тот tenant в результатах»	`filterBy` scoped-токена не включает поле tenant или приложение шлёт OR-фильтр, который расширяет. См. Изоляция арендаторов.
«После реиндекса сменилась сортировка»	Поменялся `default_sorting_field`. Diff схемы — в audit log.
«Синонимы не применяются»	Набор синонимов не попал в `synonymSets` реиндекса. Переприменить.

Если документ в дашборде есть, а поиск не возвращает — подозревайте index: true в схеме или отсутствие поля в query_by. Дашборд хранит документ; движок не обязан искать по каждому полю.

Auth / origin / rate-limit

HTTP	Body	Причина	Фикс
401	`missing_bearer_token`	Нет `Authorization`.	Слать `Authorization: Bearer ss_search_…`.
401	`invalid_or_revoked_key`	Отозван / удалён / битый.	API keys → статус. Создать новый.
401	`invalid_or_expired_scoped_token`	`exp` в прошлом или HMAC не сходится.	Свежий токен. Если сразу после mint — мог ротироваться `BETTER_AUTH_SECRET`.
403	`origin_not_allowed`	`Origin` не в allow-list ключа.	Добавить. См. Origin allow-list.
403	`scope_denied`	Не та область.	Ключ с нужной областью. Search ≠ ingest ≠ admin.
403	`tenant_mismatch`	Индекс в другой организации.	Ключ из той org, что владеет индексом.
429	`rate_limited`	Бакет ключа выбран.	Ждать следующую минуту. Лимиты.

Server-side errors

HTTP	Body	Причина	Фикс
500	`internal_error` + `requestId`	Необработанное исключение. Всегда — эскалация с request id.	Тикет с request id и таймстампом.
502	нет / HTML	Edge proxy не дошёл до upstream.	Статус. Зелёный — retry; нет — ждать инцидент.
503	`degraded`	Upstream деградирует; рубим часть трафика для восстановления.	Backoff. Статус расскажет, почему.
504	нет	Поиск > 10 секунд. Почти всегда — кривой query.	Проверить query. `filter_by` без подсказки индекса может сканить всё.

Устаревшие или отсутствующие документы

Документ загружен N секунд назад — нет в поиске. Pipeline:

Приложение
     │  POST /api/orpc/searchDocument.bulkUpsert
     ▼
SearchIngestBuffer (строка PostgreSQL)
     │  Воркер забирает
     ▼
Typesense bulkUpsert
     │  Документ ищется
     ▼
Аудит + аналитика

Где может застрять:

Приложение → API — 4xx и не было retry.
API → буфер — строка есть, processedAt null (воркер ещё не дошёл).
Воркер → Typesense — у строки failedAt и сообщение об ошибке.

Диагностика:

Dashboard → Diagnostics — найти по docId, прочитать таймлайн.
Статус буфера — searchIndex.getIngestStatus.
Retry — retry-воркер до 5 попыток. Если attempts >= 5 и failedAt стоит — сообщение в lastError — ваш фикс.

Если буфер «succeeded», а документа нет — подозревайте memory pressure Typesense или свап, прошедший без подхвата свежих записей. Тикет с document id.

Документы исчезают

Был — нет. По частоте:

Удалили. audit_log.action = bulk_delete_documents или delete_documents_by_filter.
Реиндекс выбросил. Реиндекс тянет из вашего источника. Источник потерял — реиндекс не повезёт.
Удалил коннектор. PrestaShop/Bitrix/Shopify зеркалят CMS. Удалили в CMS — удалится здесь.
Typesense рестартанул из снапшота. Очень редко. Подозреваете — запросите verification report.

Действие: найти строку удаления в audit log. Если нет — это вариант 4, эскалация.

Проблемы реиндекса

Симптом	Причина / фикс
Прогресс «застрял» на X %	Прогресс обновляется каждые 1 000 документов. На 10 млн «застрял на 50 %» может значить активный push 4 999. Подождите 60 сек.
Реиндекс закончился — новых полей нет	source query их не включал. Проверьте payload источника.
Doc count меньше ожидаемого	source filter исключает строки, которые вы хотели.
Падение посередине	См. Реиндекс — когда падает.

Проблемы дашборда

Симптом	Причина / фикс
Sign-in зацикливается на странице входа	Браузер блокирует third-party cookies для auth-сабдомена. Разрешите cookies для `app.aacsearch.com`.
404 на проект, который видит коллега	Не та организация. Используйте org-switcher.
Список индексов пуст	То же либо не тот проект ключа. Project-switcher.
Аналитика расходится с API	Аналитика eventually consistent — до 5 минут.

Когда эскалировать

Если симптома нет в дереве или дошли до листа «реально саппорту» — открывайте тикет по эскалации. Обязательно включите:

Request id (заголовок x-request-id) с упавшего запроса.
Таймстамп UTC.
Org id, project id, index slug.
Что уже проверили из этой страницы.

См. также

Статус и инциденты — сначала туда
Мониторинг — увидеть до тикета
Эскалация саппорту — что класть в тикет

Диагностика

On this page