# FAQ по устранению проблем

Решения типовых проблем Synapse.

## Не могу войти

### Симптомы

- `POST /login` возвращает 401
- «Invalid email or password»

### Решения

1. **Проверьте email** — чувствителен к регистру
2. **Проверьте пароль** — минимум 6 символов
3. **Сначала зарегистрируйтесь**, если нет аккаунта: `POST /register`
4. **Сбросьте пароль** (если настроен SMTP) через веб-интерфейс

## Я потерял Mind Key

### Симптомы

- Не могу получить доступ к воспоминаниям
- Mind Key удалён/потерян

### Решения

Mind Key нельзя восстановить. Необходимо:

1. Войти для получения JWT: `POST /login`
2. Получить список mind: `GET /minds` (с JWT)
3. Создать новый mind: `POST /minds`
4. Сохранить новый Mind Key
5. (Опционально) Удалить старый mind: `DELETE /minds/:id`

**Данные в старом mind утеряны**, если вы не сможете найти Mind Key.

## API-вызовы возвращают 401

### Симптомы

- Все API-вызовы возвращают 401 Unauthorized
- «Mind Key fehlt oder ungültig»

### Решения

1. **Проверьте формат заголовка**: `Authorization: Bearer mk_...`
2. **Проверьте, что Mind Key начинается с `mk_`** (а не `eyJ` — это JWT)
3. **Протестируйте напрямую**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
4. **Mind Key мог быть отозван** — создайте новый mind

См. [Аутентификация](/docs/getting-started/authentication).

## API-вызовы возвращают 404

### Симптомы

- 404 Not Found
- «Route not found»

### Решения

> [!CRITICAL]
> Не угадывайте пути эндпоинтов. Существуют только пути из `GET /endpoints`.

1. **Проверьте допустимые эндпоинты**: `curl https://synapse.schaefer.zone/endpoints`
2. **Сравните URL точно** — чувствителен к регистру, без trailing-слешей
3. **Проверьте HTTP-метод** — `GET /memory` и `POST /memory` различаются

## API-вызовы возвращают 429

### Симптомы

- 429 Too Many Requests
- «Rate limit exceeded»

### Решения

1. **Перейдите на header-auth** (без лимита):
   ```bash
   # Don't
   curl ".../memory/recall?key=mk_..."
   
   # Do
   curl -H "Authorization: Bearer mk_..." .../memory/recall
   ```
2. **Подождите `Retry-After` секунд**, если необходимо использовать `?key=`

См. [Лимиты запросов](/docs/api/rate-limits).

## Поиск по памяти возвращает пустой результат

### Симптомы

- `GET /memory/search?q=...` возвращает пусто
- Знаю, что воспоминания есть

### Решения

1. **Убедитесь, что воспоминания существуют**: `GET /memory/recall`
2. **Проверьте синтаксис поиска** — у FTS5 специфический синтаксис
3. **Попробуйте более простой запрос** — `?q=docker` вместо `?q=docker+swarm+deployment`
4. **Используйте семантический поиск** для концептуальных запросов: `GET /memory/semantic-search?q=...`

См. [FTS5-поиск](/docs/concepts/fts5-search).

## Воспоминания не сохраняются

### Симптомы

- POST /memory возвращает успех
- GET /memory/recall не показывает их

### Решения

1. **Убедитесь, что тот же Mind Key** — разные ключи = разные mind
2. **Проверьте ответ** — POST возвращает `{ "id": "mem_...", "status": "stored" }`
3. **Попробуйте GET /memory** (JSON-список) вместо /memory/recall (текст)
4. **Проверьте фильтр** — `?category=` или `?tag=` могут скрывать их

## Инструменты не появляются в Claude Desktop

### Симптомы

- Claude Desktop показывает 0 инструментов
- Нет иконки 🔌

### Решения

1. **Полностью перезапустите Claude Desktop** (Cmd+Q)
2. **Проверьте, что файл конфигурации** — валидный JSON
3. **Убедитесь, что установлен Node.js 18+**
4. **Запустите MCP вручную**: `npx -y synapse-mcp-api@latest`
5. **Проверьте логи**: `~/Library/Logs/Claude/mcp.log`

См. [Устранение проблем MCP](/docs/mcp/troubleshooting).

## Synapse недоступен

### Симптомы

- Не удаётся подключиться к synapse.schaefer.zone
- curl тайм-аутится

### Решения

1. **Проверьте интернет** — попробуйте другой сайт
2. **Проверьте здоровье Synapse**: `curl https://synapse.schaefer.zone/health`
3. **Подождите** — возможен временный сбой или развёртывание
4. **Проверьте страницу статуса** (если есть)

Для self-hosted: проверьте статус Docker-контейнера, подключение к БД.

## Ошибки базы данных

### Симптомы

- 500 Internal Server Error
- «Database connection failed»

### Решения

Для self-hosted:

1. **Проверьте, что PostgreSQL запущен**: `docker ps | grep postgres`
2. **Проверьте DATABASE_URL** в окружении
3. **Проверьте миграции**: `npm run migrate:check`
4. **Проверьте место на диске**: `df -h`

Для хостинга: сообщите в поддержку.

## Вебхук не срабатывает

### Симптомы

- Зарегистрировали вебхук, но колбэки не приходят
- Нет POST на ваш URL

### Решения

1. **Убедитесь, что URL доступен**: `curl -X POST your-url -d '{}'`
2. **Проверьте фильтр событий** — `memory.*` соответствует всем событиям памяти
3. **Протестируйте вебхук**: `POST /webhooks/:id/test`
4. **Проверьте, что вебхук включён**: `GET /webhooks/:id`
5. **Проверьте SSL** — Synapse требует валидный HTTPS для URL вебхуков

См. [Webhooks API](/docs/api/webhooks).

## Cron-задача не запускается

### Симптомы

- Создали cron-задачу, но она не срабатывает
- `next_run` не обновляется

### Решения

1. **Проверьте синтаксис расписания** — должен быть валидный 5-полейный cron ИЛИ целое число секунд
2. **Убедитесь, что эндпоинт разрешён** — должен быть http(s), без приватных IP
3. **Проверьте, что задача включена**: `GET /cron`
4. **Дождитесь следующего запланированного времени** — cron не мгновенный

См. [Cron и планировщик](/docs/api/cron).

## Нужно больше помощи?

1. **Проверьте существующую документацию**: <https://synapse.schaefer.zone/docs>
2. **Поиск по документации**: `GET /docs/search?q=your+question`
3. **Создайте issue**: <https://gitlab.com/schaefer-services/synapse/-/issues>
4. **Контакт**: см. страницу `/support`

## Следующие шаги

- [Ошибки и обработка ошибок](/docs/api/errors)
- [FAQ по API](/docs/faq/api-faq)
- [Устранение проблем MCP](/docs/mcp/troubleshooting)