fix: wrap document upload failures in DocumentTranslationException

translate_document() called translate_document_upload() outside its
error handling, so an upload failure raised the underlying exception
(e.g. QuotaExceededException) instead of DocumentTranslationException.
Upload failures are now wrapped too, with document_handle set to None
and the original exception as the cause. Argument errors (ValueError,
TypeError) are still raised unwrapped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: hive-bot

deepl/exceptions.py

@@ -76,14 +76,19 @@ class DocumentTranslationException(DeepLException):
     """Error occurred while translating document.
 
     :param message: Message describing the error that occurred.
-    :param document_handle: The document handle of the associated document.
+    :param document_handle: The document handle of the associated document,
+        or None if the error occurred before the document was uploaded.
     """
 
-    def __init__(self, message: str, document_handle: DocumentHandle):
+    def __init__(
+        self, message: str, document_handle: Optional[DocumentHandle]
+    ):
         super().__init__(message)
         self.document_handle = document_handle
 
     def __str__(self):
+        if self.document_handle is None:
+            return super().__str__()
         return f"{super().__str__()}, document handle: {self.document_handle}"
 
     @property

deepl/translator.py

@@ -649,8 +649,8 @@ def translate_document_from_filepath(
             allows the number of billed characters to be queried.
 
         :raises DocumentTranslationException: If an error occurs during
-            translation. The exception includes information about the document
-            request.
+            upload or translation. The exception includes the document handle
+            if the document was already uploaded, otherwise the handle is None.
         """
         _check_target_lang_given(
             "translate_document_from_filepath", target_lang
@@ -757,26 +757,33 @@ def translate_document(
             allows the number of billed characters to be queried.
 
         :raises DocumentTranslationException: If an error occurs during
-            translation, the exception includes the document handle.
+            upload or translation. The exception includes the document handle
+            if the document was already uploaded, otherwise the handle is None.
         """
         _check_target_lang_given("translate_document", target_lang)
 
-        handle = self.translate_document_upload(
-            input_document,
-            target_lang=target_lang,
-            source_lang=source_lang,
-            formality=formality,
-            glossary=glossary,
-            glossary_ids=glossary_ids,
-            style_rule=style_rule,
-            style_profile=style_profile,
-            translation_memory=translation_memory,
-            translation_memory_threshold=translation_memory_threshold,
-            filename=filename,
-            output_format=output_format,
-            enable_watermark=enable_watermark,
-            extra_body_parameters=extra_body_parameters,
-        )
+        try:
+            handle = self.translate_document_upload(
+                input_document,
+                target_lang=target_lang,
+                source_lang=source_lang,
+                formality=formality,
+                glossary=glossary,
+                glossary_ids=glossary_ids,
+                style_rule=style_rule,
+                style_profile=style_profile,
+                translation_memory=translation_memory,
+                translation_memory_threshold=translation_memory_threshold,
+                filename=filename,
+                output_format=output_format,
+                enable_watermark=enable_watermark,
+                extra_body_parameters=extra_body_parameters,
+            )
+        except (TypeError, ValueError):
+            # Invalid arguments, rejected before anything is sent.
+            raise
+        except Exception as e:
+            raise DocumentTranslationException(str(e), None) from e
 
         try:
             status = self.translate_document_wait_until_done(handle, timeout_s)

tests/offline/test_translate_document.py

@@ -481,6 +481,21 @@ def test_raises_with_handle_when_document_translation_fails(mocked):
     assert exc_info.value.document_handle.document_id == "doc-1"
 
 
+def test_wraps_upload_failure_without_handle(mocked):
+    mocked.post(url("v2/document"), status=456, json={"message": "limit"})
+
+    with pytest.raises(deepl.DocumentTranslationException) as exc_info:
+        make_translator().translate_document(
+            b"hello", io.BytesIO(), target_lang="DE", filename="a.txt"
+        )
+
+    assert exc_info.value.document_handle is None
+    assert isinstance(exc_info.value.__cause__, deepl.QuotaExceededException)
+    assert "Quota for this billing period has been exceeded" in str(
+        exc_info.value
+    )
+
+
 def test_raises_with_handle_when_document_status_fails(mocked):
     reply_with_handle(
         mocked,