[tkkhq]

Tracking

• Tracks: https://konghq.atlassian.net/browse/VOL-1428

• Related: https://github.com/Kong/volcano-hosting/pull/3400

• Related: docs(database): explain capacity refusal and safe retry guidance volcano-docs#189

• Related: fix(transport): preserve retry delay on service unavailable responses volcano-sdk-ruby#378

• Related: https://github.com/Kong/volcano-monitoring/pull/139

Why

• Database capacity refusals can return HTTP 503 with Retry-After, but Python drops that retry delay when constructing ServerError. Applications need the server's delay to bound their own retries.

Summary

• preserve numeric Retry-After on HTTP 503 as well as 429 without automatically replaying the request
• verify typed error metadata and exactly one transport request in the native error-mapping test
• retain the SDK's existing OpenAPI snapshot and generated client; no method or response-body schema changes are needed
• coordinate the public database guidance in Kong/volcano-docs; publish that guidance after the Hosting and SDK behavior is released

Verification

• Before the fix, the HTTP 503 case failed because retry_after was None instead of 17.
• uvx --from uv==0.12.17 uv run poe test — 3,007 passed.
• uvx --from uv==0.12.17 uv run poe lint
• uvx --from uv==0.12.17 uv run poe types
• uvx --from uv==0.12.17 uv run poe format-check
• uvx --from uv==0.12.17 uv run poe generated
• uvx --from uv==0.12.17 uv run poe package-check — isolated wheel/sdist installation and synthetic HTTP quickstart passed.
• No package publication or live SDK acceptance is claimed.