feat(errors): include usage details in LengthFinishReasonError

Author: RobertCraigie

Diff for: src/openai/_exceptions.py

@@ -2,14 +2,17 @@
 
 from __future__ import annotations
 
-from typing import Any, Optional, cast
+from typing import TYPE_CHECKING, Any, Optional, cast
 from typing_extensions import Literal
 
 import httpx
 
 from ._utils import is_dict
 from ._models import construct_type
 
+if TYPE_CHECKING:
+    from .types import CompletionUsage
+
 __all__ = [
     "BadRequestError",
     "AuthenticationError",
@@ -130,10 +133,19 @@ class InternalServerError(APIStatusError):
 
 
 class LengthFinishReasonError(OpenAIError):
-    def __init__(self) -> None:
-        super().__init__(
-            f"Could not parse response content as the length limit was reached",
-        )
+    usage: CompletionUsage | None
+    """The usage details for the completion that caused this error.
+
+    Note: this will *not* be set when streaming.
+    """
+
+    def __init__(self, *, usage: CompletionUsage | None) -> None:
+        msg = "Could not parse response content as the length limit was reached"
+        if usage:
+            msg += f" - {usage}"
+
+        super().__init__(msg)
+        self.usage = usage
 
 
 class ContentFilterFinishReasonError(OpenAIError):

Diff for: src/openai/lib/_parsing/_completions.py

@@ -69,7 +69,7 @@ def parse_chat_completion(
     choices: list[ParsedChoice[ResponseFormatT]] = []
     for choice in chat_completion.choices:
         if choice.finish_reason == "length":
-            raise LengthFinishReasonError()
+            raise LengthFinishReasonError(usage=chat_completion.usage)
 
         if choice.finish_reason == "content_filter":
             raise ContentFilterFinishReasonError()

Diff for: src/openai/lib/streaming/chat/_completions.py

@@ -394,7 +394,9 @@ def _accumulate_chunk(self, chunk: ChatCompletionChunk) -> ParsedChatCompletionS
 
                 if has_parseable_input(response_format=self._response_format, input_tools=self._input_tools):
                     if choice.finish_reason == "length":
-                        raise LengthFinishReasonError()
+                        # at the time of writing, `.usage` will always be `None` but
+                        # we include it here in case that is changed in the future
+                        raise LengthFinishReasonError(usage=completion_snapshot.usage)
 
                     if choice.finish_reason == "content_filter":
                         raise ContentFilterFinishReasonError()