Surface Retry-After header in error envelope for rate-limited responses

[tammersaleh]

Feature request

When a Calendar API call returns a rate-limit response (HTTP 429, or 403 with reason rateLimitExceeded / userRateLimitExceeded), Google often returns a Retry-After response header indicating when the client may safely retry. Currently gws does not surface that header value to callers - the error JSON it forwards on stderr only carries Google's standard error envelope:

{"error":{"code":429,"message":"...","errors":[{"reason":"rateLimitExceeded"}]}}

Downstream tools that wrap gws for retry have no way to honor Retry-After and must fall back to a fixed exponential schedule.

Suggested shape

Add retry_after_seconds (or retryAfter - whatever fits gws conventions) to the error envelope when the response carried a Retry-After header. Empty/absent when the header was not present.

{"error":{"code":429,"message":"...","errors":[{"reason":"rateLimitExceeded"}],"retryAfterSeconds":17}}

Or, alternatively, a top-level sibling field outside error:

{"error":{...},"retryAfterSeconds":17}

The header can be either an integer number of seconds OR an HTTP-date; gws should normalize to seconds-from-now to keep downstream parsing simple.

This would also be useful for 500/503 responses, where Google sometimes returns Retry-After to throttle clients during incidents.

Notes

• Header name in Google's responses is Retry-After. RFC 7231 §7.1.3.
• Calendar API documents the header in their usage limits and rate-limiting docs.
• No security or backwards-compat concern - this is purely additive to the error envelope.