timeout_error_summary.py 2.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263
  1. """Phase-specific one-liners for transport-timeout API errors.
  2. A timeout that survives the retry loop otherwise surfaces as the SDK's bare
  3. text: ``Request timed out.`` (openai ``APITimeoutError``) or ``timed out`` (a
  4. raw httpx ``ReadTimeout`` mid-stream). Neither says whether a connection was
  5. ever made, nor which setting to raise. The openai SDK wraps EVERY httpx
  6. timeout, connect included, in ``APITimeoutError``, so the phase is read from
  7. the most specific timeout in the explicit ``__cause__`` chain. ``__context__``
  8. is not followed: an HTTP error raised while a timeout was being handled is a
  9. different failure and keeps its own summary.
  10. """
  11. from __future__ import annotations
  12. from typing import Optional
  13. # No TCP/TLS connection was established: raising the read timeout will not help.
  14. _CONNECT_TIMEOUT_TYPES = frozenset({"ConnectTimeout", "ConnectTimeoutError"})
  15. # The request was sent (or a stream was open) but no bytes arrived in time.
  16. # ``APITimeoutError`` without a transport cause also lands here.
  17. _READ_TIMEOUT_TYPES = frozenset({
  18. "ReadTimeout", "TimeoutException", "ReadTimeoutError", "APITimeoutError",
  19. })
  20. # Waiting for a pooled connection or while uploading the request: the provider
  21. # never got to answer, so neither hint applies and the existing summary stays.
  22. _OTHER_TIMEOUT_TYPES = frozenset({"PoolTimeout", "WriteTimeout"})
  23. def _timeout_phase(error: BaseException) -> Optional[str]:
  24. """``"connect"``, ``"read"``, or ``None`` when no timeout is in the chain."""
  25. phase = None
  26. current: Optional[BaseException] = error
  27. seen: set[int] = set()
  28. while current is not None and id(current) not in seen:
  29. seen.add(id(current))
  30. name = type(current).__name__
  31. if name in _CONNECT_TIMEOUT_TYPES:
  32. return "connect"
  33. if name in _OTHER_TIMEOUT_TYPES:
  34. return None
  35. if name not in _READ_TIMEOUT_TYPES:
  36. break
  37. phase = "read"
  38. current = current.__cause__
  39. return phase
  40. def summarize_timeout_error(error: BaseException, provider: Optional[str] = None) -> Optional[str]:
  41. """Timeout summary naming the phase and the setting to change, or ``None``
  42. for any other error (the caller's existing summary handling then applies).
  43. Both lines keep the "timed out" wording: cron failure notices and the error
  44. classifier re-read this summary as text and match on it.
  45. """
  46. phase = _timeout_phase(error)
  47. if phase == "connect":
  48. return ("Connection to the provider timed out before it was established "
  49. "(check the base_url and network path)")
  50. if phase == "read":
  51. key = provider.strip() if isinstance(provider, str) and provider.strip() else "<provider>"
  52. return ("Request timed out waiting for the provider to respond (if the model needs "
  53. f"longer, raise providers.{key}.request_timeout_seconds in config.yaml)")
  54. return None