[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-python#428

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

Why

• Database capacity refusals can return HTTP 503 with Retry-After, but Ruby 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 nil instead of 17.
• bundle exec rake quality:spec quality:generated quality:package — 2,197 examples passed, 100% line/branch coverage; generated boundary and isolated gem quickstart passed after installing the locked generator dependency with npm ci --ignore-scripts --no-audit --no-fund.
• bundle exec rake quality:types
• bundle exec rubocop lib/volcano/transport.rb spec/volcano/error_mapping_spec.rb
• bundle exec rspec spec/volcano/error_mapping_spec.rb — 14 examples passed after the final test-only lint fix.
• No package publication or live SDK acceptance is claimed.