Comment

lib/sync.js

@@ -549,6 +549,12 @@ SyncApi.prototype._sync = function(syncOptions) {
             // This is the first failure, which may be spurious. To avoid unnecessary
             // connection error warnings we simply retry the /sync immediately. Only
             // if *that* one fails too do we say the connection has been lost.
+            // Examples of when this may happen are:
+            //   - Restarting backend servers. (In an HA world backends may be
+            //     restarted all the time, and its easiest just to make the
+            //     client retry).
+            //   - Intermediate proxies restarting.
+            //   - Device network changes.
             // Should we emit a state like "MAYBE_CONNETION_LOST"?
             self._syncConnectionLost = true;
             self._sync(syncOptions);