diff --git a/crates/stringflow-py/src/lib.rs b/crates/stringflow-py/src/lib.rs
index d031c1a..5e09f79 100644
--- a/crates/stringflow-py/src/lib.rs
+++ b/crates/stringflow-py/src/lib.rs
@@ -3,9 +3,15 @@ use pyo3::prelude::*;
 
 fn to_py_err(e: stringflow::Error) -> PyErr {
     match &e {
-        stringflow::Error::Unavailable(_) => PyErr::new::<PyConnectionError, _>(e.to_string()),
-        stringflow::Error::RequestFailed(_) => PyErr::new::<PyRuntimeError, _>(e.to_string()),
-        stringflow::Error::EmptyResponse => PyErr::new::<PyRuntimeError, _>(e.to_string()),
+        stringflow::Error::Unavailable(_) => {
+            PyErr::new::<PyConnectionError, _>(format!("[connection] {e}"))
+        }
+        stringflow::Error::RequestFailed(_) => {
+            PyErr::new::<PyRuntimeError, _>(format!("[request] {e}"))
+        }
+        stringflow::Error::EmptyResponse => {
+            PyErr::new::<PyRuntimeError, _>(format!("[empty_response] {e}"))
+        }
     }
 }
 
diff --git a/py/stringflow/core.pyi b/py/stringflow/core.pyi
index 85c5d9b..363d7f9 100644
--- a/py/stringflow/core.pyi
+++ b/py/stringflow/core.pyi
@@ -8,9 +8,22 @@ def chat(
     auth_header: str | None = None,
     auth_value: str | None = None,
 ) -> str:
-    """Low-level: send a chat request. Returns the response text."""
+    """Low-level: send a chat request. Returns the response text.
+
+    Raises:
+        ConnectionError: ``[connection] ...`` when the server is unreachable.
+        RuntimeError: ``[request] ...`` when the API returns an error, or
+            ``[empty_response] ...`` when the model returns no content.
+        ValueError: When *wire_format* is not a recognised format.
+    """
     ...
 
 def health_check(base_url: str) -> str:
-    """Low-level: send a health check. Returns the status string."""
+    """Low-level: send a health check. Returns the status string.
+
+    Raises:
+        ConnectionError: ``[connection] ...`` when the server is unreachable.
+        RuntimeError: ``[request] ...`` when the server returns an error, or
+            ``[empty_response] ...`` when the response has no content.
+    """
     ...