api: Add UnrecoverableNetworkError Exception & use in do_api_query.

This replaces one case where the base ZulipError was raised, and another
where the original exception was re-raised.

This method, and so all API calls, should now only fail via raising this
Exception or by a non-'success' result in the return value dict; this
should avoid leaking any implementation detail and clarify expectations
in user code.

zulip/zulip/__init__.py

@@ -294,6 +294,9 @@ class ConfigNotFoundError(ZulipError):
 class MissingURLError(ZulipError):
     pass
 
+class UnrecoverableNetworkError(ZulipError):
+    pass
+
 class Client(object):
     def __init__(self, email=None, api_key=None, config_file=None,
                  verbose=False, retry_on_errors=True,
@@ -565,7 +568,7 @@ class Client(object):
                 # non-timeout other SSLErrors
                 if (isinstance(e, requests.exceptions.SSLError) and
                         str(e) != "The read operation timed out"):
-                    raise
+                    raise UnrecoverableNetworkError('SSL Error')
                 if longpolling:
                     # When longpolling, we expect the timeout to fire,
                     # and the correct response is to just retry
@@ -580,7 +583,7 @@ class Client(object):
                     # go into retry logic, because the most likely scenario here is
                     # that somebody just hasn't started their server, or they passed
                     # in an invalid site.
-                    raise ZulipError('cannot connect to server ' + self.base_url)
+                    raise UnrecoverableNetworkError('cannot connect to server ' + self.base_url)
 
                 if error_retry(""):
                     continue