Default to adding idempotecy-key to audit-logs/events if not present, added in retryability logic to endpoints

src/workos/audit_logs.py

@@ -1,7 +1,10 @@
+import uuid
 from typing import Optional, Protocol, Sequence
 
 from workos.types.audit_logs import AuditLogExport
 from workos.types.audit_logs.audit_log_event import AuditLogEvent
+from workos.types.audit_logs.audit_log_event_response import AuditLogEventResponse
+from workos.utils._base_http_client import RetryConfig
 from workos.utils.http_client import SyncHTTPClient
 from workos.utils.request_helper import REQUEST_METHOD_GET, REQUEST_METHOD_POST
 
@@ -18,15 +21,15 @@ def create_event(
         organization_id: str,
         event: AuditLogEvent,
         idempotency_key: Optional[str] = None,
-    ) -> None:
+    ) -> AuditLogEventResponse:
         """Create an Audit Logs event.
 
         Kwargs:
             organization_id (str): Organization's unique identifier.
             event (AuditLogEvent): An AuditLogEvent object.
             idempotency_key (str): Idempotency key. (Optional)
         Returns:
-            None
+            AuditLogEventResponse: Response indicating success
         """
         ...
 
@@ -78,17 +81,27 @@ def create_event(
         organization_id: str,
         event: AuditLogEvent,
         idempotency_key: Optional[str] = None,
-    ) -> None:
+    ) -> AuditLogEventResponse:
         json = {"organization_id": organization_id, "event": event}
 
         headers = {}
-        if idempotency_key:
-            headers["idempotency-key"] = idempotency_key
+        # Auto-generate UUID v4 if not provided
+        if idempotency_key is None:
+            idempotency_key = f"workos-python-{uuid.uuid4()}"
 
-        self._http_client.request(
-            EVENTS_PATH, method=REQUEST_METHOD_POST, json=json, headers=headers
+        headers["idempotency-key"] = idempotency_key
+
+        # Enable retries for audit log event creation with default retryConfig
+        response = self._http_client.request(
+            EVENTS_PATH,
+            method=REQUEST_METHOD_POST,
+            json=json,
+            headers=headers,
+            retry_config=RetryConfig(),
         )
 
+        return AuditLogEventResponse.model_validate(response)
+
     def create_export(
         self,
         *,

src/workos/types/audit_logs/__init__.py

@@ -2,5 +2,6 @@
 from .audit_log_event_context import *
 from .audit_log_event_target import *
 from .audit_log_event import *
+from .audit_log_event_response import *
 from .audit_log_export import *
 from .audit_log_metadata import *

src/workos/types/audit_logs/audit_log_event_response.py

@@ -0,0 +1,7 @@
+from workos.types.workos_model import WorkOSModel
+
+
+class AuditLogEventResponse(WorkOSModel):
+    """Response from creating an audit log event."""
+
+    success: bool

src/workos/utils/_base_http_client.py

@@ -1,4 +1,6 @@
 import platform
+import random
+from dataclasses import dataclass
 from typing import (
     Any,
     Mapping,
@@ -32,6 +34,19 @@
 
 DEFAULT_REQUEST_TIMEOUT = 25
 
+# Status codes that should trigger a retry (consistent with workos-node)
+RETRY_STATUS_CODES = [408, 500, 502, 504]
+
+
+@dataclass
+class RetryConfig:
+    """Configuration for retry logic with exponential backoff."""
+
+    max_retries: int = 3
+    base_delay: float = 1.0  # seconds
+    max_delay: float = 30.0  # seconds
+    jitter: float = 0.25  # 25% jitter
+
 
 ParamsType = Optional[Mapping[str, Any]]
 HeadersType = Optional[Dict[str, str]]
@@ -56,6 +71,7 @@ class BaseHTTPClient(Generic[_HttpxClientT]):
     _base_url: str
     _version: str
     _timeout: int
+    _retry_config: Optional[RetryConfig]
 
     def __init__(
         self,
@@ -65,12 +81,14 @@ def __init__(
         client_id: str,
         version: str,
         timeout: Optional[int] = DEFAULT_REQUEST_TIMEOUT,
+        retry_config: Optional[RetryConfig] = None,
     ) -> None:
         self._api_key = api_key
         self._base_url = base_url
         self._client_id = client_id
         self._version = version
         self._timeout = DEFAULT_REQUEST_TIMEOUT if timeout is None else timeout
+        self._retry_config = retry_config  # Store as-is, None means no retries
 
     def _generate_api_url(self, path: str) -> str:
         return f"{self._base_url}{path}"
@@ -196,6 +214,37 @@ def _handle_response(self, response: httpx.Response) -> ResponseJson:
 
         return cast(ResponseJson, response_json)
 
+    def _is_retryable_error(self, response: httpx.Response) -> bool:
+        """Determine if an error should be retried."""
+        return response.status_code in RETRY_STATUS_CODES
+
+    def _is_retryable_exception(self, exc: Exception) -> bool:
+        """Determine if an exception should trigger a retry."""
+        # Retry on network [connection, timeout] exceptions
+        if isinstance(exc, (httpx.ConnectError, httpx.TimeoutException)):
+            return True
+        return False
+
+    def _get_backoff_delay(self, attempt: int, retry_config: RetryConfig) -> float:
+        """Calculate delay with exponential backoff and jitter.
+
+        Args:
+            attempt: The current retry attempt number (0-indexed)
+            retry_config: The retry configuration
+
+        Returns:
+            The delay, in seconds, to wait before the next retry
+        """
+        # Exponential backoff: base_delay * 2^attempt
+        delay: float = retry_config.base_delay * (2**attempt)
+
+        # Cap at max_delay
+        delay = min(delay, retry_config.max_delay)
+
+        # Add jitter: random variation of 0-25% of delay
+        jitter_amount: float = delay * retry_config.jitter * random.random()
+        return delay + jitter_amount
+
     def build_request_url(
         self,
         url: str,

src/workos/utils/http_client.py

@@ -1,4 +1,5 @@
 import asyncio
+import time
 from types import TracebackType
 from typing import Optional, Type, Union
 
@@ -13,6 +14,7 @@
     JsonType,
     ParamsType,
     ResponseJson,
+    RetryConfig,
 )
 from workos.utils.request_helper import REQUEST_METHOD_GET
 
@@ -38,6 +40,7 @@ def __init__(
         client_id: str,
         version: str,
         timeout: Optional[int] = None,
+        retry_config: Optional[RetryConfig] = None,
         # If no custom transport is provided, let httpx use the default
         # so we don't overwrite environment configurations like proxies
         transport: Optional[httpx.BaseTransport] = None,
@@ -48,6 +51,7 @@ def __init__(
             client_id=client_id,
             version=version,
             timeout=timeout,
+            retry_config=retry_config,
         )
         self._client = SyncHttpxClientWrapper(
             base_url=base_url,
@@ -88,6 +92,7 @@ def request(
         json: JsonType = None,
         headers: HeadersType = None,
         exclude_default_auth_headers: bool = False,
+        retry_config: Optional[RetryConfig] = None,
     ) -> ResponseJson:
         """Executes a request against the WorkOS API.
 
@@ -98,6 +103,7 @@ def request(
             method (str): One of the supported methods as defined by the REQUEST_METHOD_X constants
             params (ParamsType): Query params to be added to the request
             json (JsonType): Body payload to be added to the request
+            retry_config (RetryConfig): Optional retry configuration. If None, no retries.
 
         Returns:
             ResponseJson: Response from WorkOS
@@ -110,8 +116,44 @@ def request(
             headers=headers,
             exclude_default_auth_headers=exclude_default_auth_headers,
         )
-        response = self._client.request(**prepared_request_parameters)
-        return self._handle_response(response)
+
+        # If no retry config provided, just make the request without retry logic
+        if retry_config is None:
+            response = self._client.request(**prepared_request_parameters)
+            return self._handle_response(response)
+
+        # Retry logic enabled
+        last_exception = None
+
+        for attempt in range(retry_config.max_retries + 1):
+            try:
+                response = self._client.request(**prepared_request_parameters)
+
+                # Check if we should retry based on status code
+                if attempt < retry_config.max_retries and self._is_retryable_error(
+                    response
+                ):
+                    delay = self._get_backoff_delay(attempt, retry_config)
+                    time.sleep(delay)
+                    continue
+
+                # No retry needed or max retries reached
+                return self._handle_response(response)
+
+            except Exception as exc:
+                last_exception = exc
+                if attempt < retry_config.max_retries and self._is_retryable_exception(
+                    exc
+                ):
+                    delay = self._get_backoff_delay(attempt, retry_config)
+                    time.sleep(delay)
+                    continue
+                raise
+
+        if last_exception is not None:
+            raise last_exception
+
+        raise RuntimeError("Unexpected state in retry logic")
 
 
 class AsyncHttpxClientWrapper(httpx.AsyncClient):
@@ -138,6 +180,7 @@ def __init__(
         client_id: str,
         version: str,
         timeout: Optional[int] = None,
+        retry_config: Optional[RetryConfig] = None,
         # If no custom transport is provided, let httpx use the default
         # so we don't overwrite environment configurations like proxies
         transport: Optional[httpx.AsyncBaseTransport] = None,
@@ -148,6 +191,7 @@ def __init__(
             client_id=client_id,
             version=version,
             timeout=timeout,
+            retry_config=retry_config,
         )
         self._client = AsyncHttpxClientWrapper(
             base_url=base_url,
@@ -185,6 +229,7 @@ async def request(
         json: JsonType = None,
         headers: HeadersType = None,
         exclude_default_auth_headers: bool = False,
+        retry_config: Optional[RetryConfig] = None,
     ) -> ResponseJson:
         """Executes a request against the WorkOS API.
 
@@ -195,6 +240,7 @@ async def request(
             method (str): One of the supported methods as defined by the REQUEST_METHOD_X constants
             params (ParamsType): Query params to be added to the request
             json (JsonType): Body payload to be added to the request
+            retry_config (RetryConfig): Optional retry configuration. If None, no retries.
 
         Returns:
             ResponseJson: Response from WorkOS
@@ -207,8 +253,46 @@ async def request(
             headers=headers,
             exclude_default_auth_headers=exclude_default_auth_headers,
         )
-        response = await self._client.request(**prepared_request_parameters)
-        return self._handle_response(response)
+
+        # If no retry config provided, just make the request without retry logic
+        if retry_config is None:
+            response = await self._client.request(**prepared_request_parameters)
+            return self._handle_response(response)
+
+        # Retry logic enabled
+        last_exception = None
+
+        for attempt in range(retry_config.max_retries + 1):
+            try:
+                response = await self._client.request(**prepared_request_parameters)
+
+                # Check if we should retry based on status code
+                if attempt < retry_config.max_retries and self._is_retryable_error(
+                    response
+                ):
+                    delay = self._get_backoff_delay(attempt, retry_config)
+                    await asyncio.sleep(delay)
+                    continue
+
+                # No retry needed or max retries reached
+                return self._handle_response(response)
+
+            except Exception as exc:
+                last_exception = exc
+                if attempt < retry_config.max_retries and self._is_retryable_exception(
+                    exc
+                ):
+                    delay = self._get_backoff_delay(attempt, retry_config)
+                    await asyncio.sleep(delay)
+                    continue
+                raise
+
+        # Should not reach here, but raise last exception if we do
+        if last_exception is not None:
+            raise last_exception
+
+        # Fallback: this should never happen
+        raise RuntimeError("Unexpected state in retry logic")
 
 
 HTTPClient = Union[AsyncHTTPClient, SyncHTTPClient]