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

Open
#777 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

  • #802 by @Lubrsy706 — closed without merging
  • #809 by @Lubrsy706 — closed without merging

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
rust
Domain
api, cli

Research direction

No source file or test is named. Start by locating the gws HTTP error-envelope handling and existing tests for forwarded API errors; then determine where Retry-After is available and how error fields are serialized. Done means 429, rate-limit 403, 500, and 503 responses preserve the header as seconds-from-now, while responses without it remain unchanged.

Written by the indexing model from the issue text.

Description

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.
Dominant language
Rust
Stars
32.3k
Forks
2k
Avg merge
16h 3m
Merged PRs (30d)
1

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from googleworkspace/cli

All issues in googleworkspace/cli

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.