Skip to main content
Quasi tutti i problemi SwitchBot vengono diagnosticati male, e sempre nello stesso modo: “la serratura è offline e la batteria è a 0%”. Nella maggior parte dei casi entrambe le affermazioni sono sbagliate, e mandano la persona sul posto a cambiare batterie che non serviva cambiare. Prima di toccare qualsiasi cosa: leggi il codice che l’API ha restituito. Il codice dice esattamente dove sta il problema.

​
La mappa dei codici (fonte ufficiale)

Dalla documentazione OpenWonderLabs/SwitchBotAPI — verificata il 22/08/2026:
161 non è “hub offline”. È l’errore opposto: il cloud SwitchBot è arrivato fino all’hub, ed è l’hub che non riesce a parlare con la serratura. Se l’hub fosse davvero giù, il codice sarebbe 171.Confondere i due manda a riavviare il router quando il problema è la distanza fra hub e serratura — e viceversa. Sono due guasti con rimedi opposti.

​
battery: 0 quasi mai significa batteria scarica

Questa è la trappola che è costata più tempo di tutte.
1

Lo schema ufficiale della Smart Lock Pro non contiene onlineStatus

I campi documentati sono deviceId, deviceType, hubDeviceId, battery, version, lockState, doorState, calibrate. Il campo onlineStatus è documentato solo per il Robot Vacuum S1 (API v1.0). Sulla serratura è un campo extra, non contrattuale: è la vista del cloud sul collegamento Bluetooth con la serratura.
2

Quando il device è davvero irraggiungibile, l'API non restituisce un body

Restituisce un codice d’errore (161 o 171) con body: {}. Non ti dà battery, lockState o doorState: non li conosce.
3

Quindi un 100 con onlineStatus offline è uno snapshot vecchio

Se leggi statusCode: 100 e dentro il body trovi onlineStatus: "offline", il cloud ti sta servendo l’ultimo stato noto. In quello snapshot battery: 0 vuol dire “non ho un valore aggiornato”, non “batteria scarica”.
La lettura della batteria via cloud è peraltro un difetto noto e mai risolto di SwitchBot (issue #304, aperta da anni: valori fermi o incoerenti con l’app).
La batteria è una diagnosi legittima in un solo caso: il device risponde 100 con uno stato fresco (onlineStatus: "online", o device che non espone quel campo) e il valore di batteria è basso. In tutti gli altri casi la batteria non c’entra e va esclusa dalle ipotesi.

​
Albero diagnostico

Tre domande in ordine. Ognuna si risponde con una chiamata in sola lettura: nessun comando viene inviato alla serratura.
1

Il device esiste per queste credenziali? Il Cloud Service è attivo?

GET /v1.1/devices — cerca il deviceId nella lista.
  • Non c’è → 152 / device rimosso o account sbagliato → problema nostro, non del cliente.
  • C’è ma enableCloudService: false → il device non è pilotabile via API. Il cliente deve riattivare “Servizi cloud” nell’app.
  • C’è e enableCloudService: true → prosegui. Annota il suo hubDeviceId.
2

La serratura risponde?

GET /v1.1/devices/<lock>/status
  • 100 con stato fresco → la serratura è viva. Se la batteria è bassa, ora è una diagnosi legittima.
  • 100 con onlineStatus: "offline", oppure 161 → la serratura non è raggiungibile. Prosegui: non sai ancora di chi è la colpa.
  • 401 / 429 / nessuna risposta → non è un guasto della serratura: è un problema nostro o un transitorio. Fermati qui e non dire nulla al cliente sullo stato della porta.
3

L'hub risponde?

GET /v1.1/devices/<hub>/status
  • 171 (o 161 sull’hub) → HUB OFFLINE: il guasto è a monte della serratura, in casa del cliente.
  • 100 → l’hub c’è, la serratura no: il guasto è nel collegamento hub↔serratura.
Gli Hub (Hub Mini compreso) non hanno una sezione “Device Status” nella documentazione: rispondono 100 con un body vuoto. L’hub quindi non si giudica dal contenuto della risposta, ma dall’assenza di 171/161.

​
Cosa chiedere al cliente, caso per caso

Chiedere le cose giuste evita il giro di messaggi da tre giorni. Una domanda per ipotesi, non un elenco generico.
Il test che chiude il caso 161. Se il cliente riesce ad aprire dall’app ma il nostro link no, c’è un’ambiguità che nessuna lettura API risolve: l’app può aprire anche via Bluetooth diretto quando sei vicino alla porta, il nostro link no — passa sempre per il cloud.Chiedi un test simultaneo: il cliente apre dall’app stando lontano da casa, nello stesso minuto in cui proviamo noi.
  • Lui apre e noi prendiamo 161 → il percorso cloud funziona per il suo account e non per il nostro: quasi sempre le nostre credenziali appartengono a un account che ha il device solo condiviso, non posseduto. Fix: rigenerare Token+Secret dall’account proprietario della Home.
  • Falliscono entrambi (lui apre solo stando vicino) → è il collegamento fisico hub↔serratura: avvicinare l’hub, rimuovere ostacoli, rifare il pairing.

​
Non dire mai all’ospite

Tre frasi da non usare mai, perché affermano un fatto che non è stato verificato:
  • “La batteria è scarica” — a meno che il device non sia raggiungibile e riporti davvero un valore basso.
  • “Il dispositivo è offline” quando la chiamata è andata in timeout o in rate limit: in quel caso non lo sai.
  • “La serratura è rotta” quando il codice è 401: è un problema di configurazione nostro, la serratura potrebbe essere perfettamente funzionante.
▷ Prompt Claude Code: Debug SwitchBot · incolla in Claude Code:

SwitchBot API (docs)

Codici, schemi per device, comandi

Metodo troubleshooting

Le 5 mosse