diff --git a/DEVICE_BEHAVIOR.md b/DEVICE_BEHAVIOR.md
index c7950f1..3016f25 100644
--- a/DEVICE_BEHAVIOR.md
+++ b/DEVICE_BEHAVIOR.md
@@ -108,6 +108,33 @@ stateDiagram-v2
 - MQTT: экспоненциальный backoff (1s → 2s → 4s → ... → max 60s)
 - При восстановлении: публикует `{UID}/status = "connected"` → сервер снова шлёт preferences
 
+> **Важно**: Публикация `status = "connected"` должна происходить в колбэке подключения MQTT,  
+> а не только при первом старте. Иначе после реконнекта устройство не получит настройки с сервера.
+
+---
+
+## Типичные ошибки реализации
+
+### 1. Неверный payload в `{UID}/status`
+```
+❌ "online", "Online", "connected\n", "1"
+✅ "connected"
+```
+Сервер проверяет точное совпадение байт. Неверный payload → `push_box_settings` не вызывается →  
+устройство работает без калибровок из БД до следующей перезагрузки.
+
+### 2. `status` публикуется только при первом старте
+При реконнекте MQTT (после обрыва WiFi, перезапуска брокера) нужно снова опубликовать  
+`{UID}/status = "connected"`. Иначе после восстановления связи настройки не придут.
+
+### 3. Pump ID отсчёт
+API использует 1-based индексацию (1–8). Прошивка внутренне хранит 0-based, но  
+MQTT-команды и HTTP API принимают 1-based. Проверять валидацию: `id ∈ [1, 8]`.
+
+### 4. HTTP API требует `Accept: application/json`
+При обращении к ponics.online API без этого заголовка сервер может вернуть 302 (редирект  
+на страницу логина) вместо JSON. Клиенты должны явно указывать `Accept: application/json`.
+
 ---
 
 ## Home Assistant интеграция (отдельный канал)
diff --git a/MQTT.md b/MQTT.md
index ea6b441..54aab77 100644
--- a/MQTT.md
+++ b/MQTT.md
@@ -92,6 +92,11 @@ sequenceDiagram
 Payload: строка `"connected"` — устройство подключилось к брокеру.  
 Триггер: сервер отправляет настройки (`set/preferences/all`).
 
+> ⚠️ **КРИТИЧНО**: Payload должен быть **точно** `"connected"` (строчные буквы, без пробелов/null).  
+> Любое другое значение (`"online"`, `"Connected"`, `"1"`) **не вызовет** `push_box_settings`.  
+> Публиковать нужно **при каждом подключении к брокеру** (первый старт + реконнект после обрыва).  
+> Источник: `message_processor.py` → `if msg.payload == b"connected": push_box_settings(box)`
+
 ### `{UID}/status/sensors`
 
 Ответ на `{UID}/cmd/status/sensors`. Поля зависят от подключённых датчиков.