# FAQ з усунення несправностей

Рішення поширених проблем Synapse.

## Не можу увійти

### Симптоми

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

### Рішення

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

## Я втратив Mind Key

### Симптоми

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

### Рішення

Mind Keys неможливо відновити. Вам потрібно:

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 точно** — чутливий до регістру, без кінцевих слешів
3. **Перевірте HTTP-метод** — `GET /memory` та `POST /memory` різні

## API-виклики повертають 429

### Симптоми

- 429 Too Many Requests
- «Rate limit exceeded»

### Рішення

1. **Перейдіть на автентифікацію через заголовок** (без обмеження):
   ```bash
   # Не робіть
   curl ".../memory/recall?key=mk_..."
   
   # Робіть
   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`

Для хостингу: зверніться до підтримки.

## Webhook не спрацьовує

### Симптоми

- Зареєстровано webhook, але не отримуєте зворотних викликів
- Немає POST на ваш URL

### Рішення

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

Дивіться [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)
- [API FAQ](/docs/faq/api-faq)
- [Усунення несправностей MCP](/docs/mcp/troubleshooting)