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

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

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

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

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 не запущен. Запустите приложение.
• «Свои интеграции» выключены. Настройки → Интеграции → «Свои интеграции» → «Включить…». Функция экспериментальная и по умолчанию выключена (см. Обзор).

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

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

{"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).
• invalid_token — токен есть, но не подходит: опечатка, чужой токен или его перевыпустили в Настройках (например, после подозрения на утечку). Возьмите актуальный токен там же: «slug» → Подключение.

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

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

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

Опечатка в адресе или интеграция ещё не создана человеком — API никогда не создаёт интеграции сам (Понятия). sparku — код 67.

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

{"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 слишком часто#

{"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.

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

Настройки → Свои интеграции → «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 и лишь потом нажимайте кнопку; см. Кнопки и события.