# Если не работает

> sparku doctor, типичные ошибки — от отсутствия сокета до 409, журнал запросов и консоль «Проверка».

## Первым делом — `sparku doctor`

```bash
sparku doctor
sparku doctor deploy   # плюс проверка токена и схемы конкретной интеграции
```

Проходит по шагам и печатает `✓`/`✗` на каждом: сокет, `/v1/health`, версия CLI
против версии приложения, а с адресом интеграции — источник токена и её поля.
Останавливается на первой проблеме и возвращает соответствующий код выхода
([CLI sparku](/docs/api/ru/cli.md#коды-выхода)).

```
sparku 2.4.0
✓ сокет: /Users/you/.sparku/run/api.sock
✓ SparkU 2.4.0, API v1
✓ токен для «deploy»: $SPARKU_TOKEN_DEPLOY
✓ интеграция «Деплой»: progress (progress), stage (state), title (text)
```

## Сокета нет

```
✗ сокета нет: /Users/you/.sparku/run/api.sock
```

Значит одно из двух:

- **SparkU не запущен.** Запустите приложение.
- **«Свои интеграции» выключены.** Настройки → Интеграции → «Свои интеграции» →
  «Включить…». Функция экспериментальная и по умолчанию выключена (см.
  [Обзор](/docs/api/ru/overview.md)).

Любой запрос к отсутствующему сокету — код `69` (`sparku`) или ошибка соединения
(`curl: (7) Failed to connect`, `ConnectionRefusedError` у Python). Скрипт может
надёжно отличить «SparkU не запущен» от прочих ошибок: недоступность проверяется
первой, до токена и адреса.

## 401 — нет или не тот токен

```json
{"error": {"code": "unauthorized", "message": "нужен токен: заголовок Authorization: Bearer <токен> (Настройки SparkU → Свои интеграции → Подключение)"}}
{"error": {"code": "invalid_token", "message": "токен не подходит к интеграции «deploy» — возможно, его перевыпустили"}}
```

- `unauthorized` — заголовка `Authorization` нет вовсе. В `sparku` это значит, что
  токен не нашёлся ни в `--token`, ни в `--token-file`, ни в
  `SPARKU_TOKEN_<АДРЕС>`, ни в `SPARKU_TOKEN` (порядок поиска —
  [CLI sparku](/docs/api/ru/cli.md#токен)).
- `invalid_token` — токен есть, но не подходит: опечатка, чужой токен или его
  перевыпустили в Настройках (например, после подозрения на утечку). Возьмите
  актуальный токен там же: «slug» → Подключение.

`sparku` в обоих случаях завершается кодом `77`.

## 404 — нет такой интеграции

```json
{"error": {"code": "unknown_integration", "message": "интеграции «deploy» нет; создайте её в Настройках SparkU → Свои интеграции"}}
```

Опечатка в адресе или интеграция ещё не создана человеком — API никогда не
создаёт интеграции сам ([Понятия](/docs/api/ru/concepts.md)). `sparku` — код `67`.

## 422 — значение не прошло проверку

```json
{"error": {"code": "invalid_fields", "message": "progress: ожидалось 0…1, пришло 70",
 "fields": [{"field": "progress", "message": "progress: ожидалось 0…1, пришло 70"}]}}
```

Текст ошибки рассчитан на то, чтобы сразу быть понятным в терминале — какое поле
и что с ним не так. Запись **всё или ничего**: если хоть одно поле в запросе не
прошло проверку, не применяется ни одно, даже если остальные были верными. Сверьте
тип и границы поля со схемой — `GET /v1/integrations/{slug}` или раздел «Поля» в
редакторе. `sparku` — код `65`.

## 429 — `notify` слишком часто

```json
{"error": {"code": "too_many_notices", "message": "notify не чаще раза в 2 с"}}
```

Заголовок ответа `Retry-After` подсказывает, сколько ждать. Это не ошибка данных —
лимит защищает от «стробоскопа», если `notify` вызывается в цикле. `sparku` — код
`75`; скрипт может ловить именно `75`, чтобы не путать частый `notify` с прочими
проблемами.

## 409 — конфликт состояния

| Код | Причина | Что делать |
|---|---|---|
| `integration_disabled` | интеграция выключена в Настройках | включить её в разделе «Свои интеграции» |
| `notify_disabled` | `notify` выключен в настройках именно этой интеграции | включить в разделе «Островок» редактора |
| `dialog_pending` | у интеграции уже есть вопрос без ответа | дождаться ответа или снятия текущего вопроса |
| `import_pending` | SparkU уже предлагает человеку другой импорт | дождаться его ответа |

Все эти коды — временное состояние, не ошибка запроса: `sparku` возвращает `69`
(«SparkU недоступен») для первых двух и то же значение для остальных — см. таблицу
кодов в [HTTP API](/docs/api/ru/http.md#коды-ошибок).

## Журнал запросов интеграции

Настройки → Свои интеграции → «slug» → раздел «Журнал» — последние 50 запросов к
этой интеграции: действие (`push`/`end`/`notify`/`ask`/`listen`/`describe`), код
ответа, текст ошибки или ответ человека, и процесс-клиент (`python3`, `curl` и
т. д. по PID на том конце сокета). Это первое место, куда стоит смотреть, когда
скрипт «вроде бы что-то отправляет», но на островке ничего не меняется: журнал
показывает, дошёл ли запрос и что ему ответил сервер, без необходимости включать
отладку на стороне скрипта.

## Консоль «Проверка» в редакторе

В редакторе интеграции (раздел «Проверка») можно отправить значения тем же путём,
что и `push`, снять их, вызвать `notify` и задать тестовый вопрос — не выходя в
терминал. Полезно, чтобы отделить «не так настроена карточка» от «скрипт шлёт не
то»: если значения из консоли отображаются на островке правильно, а из скрипта —
нет, проблема в скрипте (адрес, токен, имена полей, форма JSON), не в самой
интеграции.

## Прочее

- **Просроченные значения.** Если `GET /v1/integrations/{slug}` показывает пустой
  `values`, а вы точно писали значения, — проверьте `expires_at` в прошлом ответе:
  срок жизни (`valueLifetime` интеграции или `?ttl=`) истёк. `push` — это upsert,
  следующая запись всё восстановит.
- **Версия CLI и приложения разошлись.** `sparku doctor` печатает предупреждение,
  если `sparku` в `/usr/local/bin` симлинкует на другую копию SparkU, чем
  запущенная. Переустановите симлинк: Настройки → Свои интеграции → «Командная
  строка».
- **`sparku listen` не получает события.** Пока поток не открыт, элементы с
  действием «Событие слушателю» неактивны на самом островке — нажатие никуда не
  уходит, событие не генерируется вовсе. Откройте `listen` и лишь потом нажимайте
  кнопку; см. [Кнопки и события](/docs/api/ru/events.md).