chore(release): release zodiac-core 0.9.1

TTWShell · TTWShell · commit b3d9d862d71f · 2026-06-02T11:52:15.000+08:00
- Bump package and lockfile versions to 0.9.1
  - Add changelog and API docs for upstream error details
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.1] - 2026-06-02
+
+### Added
+
+- **HTTP**: Log translated upstream HTTP errors with structured context, including service, error type, request method, upstream URL, status code, and capped upstream response body details.
+- **Exceptions**: Include upstream status and response body details in `UpstreamRequestException` responses for upstream HTTP 400/422 failures.
+
+### Fixed
+
+- **HTTP**: Handle `httpx.RequestError` instances without request metadata without raising a secondary exception during upstream error translation.
+- **Exception Handlers**: Log inbound request context when returning standardized upstream error responses.
+- **Docs**: Document upstream error logging fields and 400/422 response details.
+
 ## [0.9.0] - 2026-04-29
 
 ### Added
diff --git a/docs/api/exceptions.md b/docs/api/exceptions.md
@@ -90,6 +90,35 @@ Classification:
 - Other upstream HTTP status failures become `UpstreamServiceException`.
 - Other `httpx.RequestError` failures become `UpstreamServiceException`.
 
+When an upstream HTTP status error is translated, ZodiacCore logs a warning with structured upstream context:
+
+- `upstream_service`
+- `upstream_error_type`
+- `upstream_method` and `upstream_url` when request metadata is available
+- `upstream_status`
+- `upstream_response_body`
+- `upstream_response_body_truncated`
+
+The response body logged in `upstream_response_body` is capped at 4096 characters. If the upstream response body has not been read, ZodiacCore logs `"<response body not read>"` instead of consuming the stream. `httpx.RequestError` instances without request metadata are still translated and logged without method or URL fields.
+
+For upstream HTTP 400/422 failures, the standard response also includes the upstream status and response body details so callers can diagnose rejected upstream requests:
+
+```json
+{
+  "code": 400,
+  "message": "Upstream request failed",
+  "data": {
+    "service": "identity_and_access",
+    "error_code": "UPSTREAM_REQUEST_ERROR",
+    "upstream_status": 422,
+    "upstream_response_body": "{\"code\":422}",
+    "upstream_response_body_truncated": false
+  }
+}
+```
+
+For other upstream HTTP status failures, the upstream response body is logged but not returned in the client response.
+
 Some upstream services always return HTTP 200 and put business failures in their response body. In that case, parse the upstream payload and raise the ZodiacCore upstream exception yourself:
 
 ```python
@@ -107,6 +136,7 @@ async def create_payment(client: ZodiacClient):
         raise UpstreamRequestException(
             service="payment_gateway",
             upstream_status=response.status_code,
+            upstream_response_body=response.text,
         )
 
     if payload["code"] != "SUCCESS":
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zodiac-core"
-version = "0.9.0"
+version = "0.9.1"
 description = "ZodiacCore-Py: A high-performance core library for modern Python web services."
 readme = "README.md"
 license = "MIT"
diff --git a/uv.lock b/uv.lock
