Add --max-retry and --max-retry-timer global flags for 429 rate limiting

Adds two new persistent flags to control retry behavior on HTTP 429 responses:
- --max-retry (default 3): max number of retry attempts before giving up
- --max-retry-timer (default 60s): max total seconds allowed across all retries

If either limit would be exceeded before the next retry, the command exits
immediately with a clear error message stating the throttle condition and how
long to wait before retrying, rather than silently sleeping through it.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mycollablab

cmd/root.go

@@ -36,6 +36,12 @@ var rootCmd = &cobra.Command{
 		paginate, _ := cmd.Flags().GetBool("paginate")
 		config.SetPaginate(paginate)
 
+		// Rate-limit retry controls
+		maxRetry, _ := cmd.Flags().GetInt("max-retry")
+		config.SetMaxRetry(maxRetry)
+		maxRetryTimer, _ := cmd.Flags().GetInt("max-retry-timer")
+		config.SetMaxRetryTimer(maxRetryTimer)
+
 		// Load app config early (safe local file read, needed by skipAuth-exempt commands like set-org)
 		cfg, err := appconfig.Load()
 		if err != nil {
@@ -172,6 +178,8 @@ func init() {
 	rootCmd.PersistentFlags().Bool("dry-run", false, "Print write requests without executing them")
 	rootCmd.PersistentFlags().String("user", "", "Use a specific authenticated user (email)")
 	rootCmd.PersistentFlags().String("organization", "", "Override organization ID for this command")
+	rootCmd.PersistentFlags().Int("max-retry", 3, "Max number of 429 retries before giving up (0 = no retries)")
+	rootCmd.PersistentFlags().Int("max-retry-timer", 60, "Max total seconds to wait across all 429 retries (0 = unlimited)")
 
 	// On flag errors (unknown flag, bad value), print usage with valid flags.
 	// SilenceUsage suppresses Cobra's automatic usage, so we print it ourselves.

internal/client/client.go

@@ -32,10 +32,22 @@ func Do(req *Request) ([]byte, int, error) {
 		body, status, headers, err = doOnce(req)
 	}
 
-	for retries := 0; status == 429 && retries < 3; retries++ {
+	var cumulativeWait time.Duration
+	for retries := 0; status == 429; retries++ {
+		maxRetry := config.MaxRetry()
+		maxTimer := time.Duration(config.MaxRetryTimer()) * time.Second
 		wait := retryAfterDuration(headers.Get("Retry-After"))
-		fmt.Fprintf(os.Stderr, "Rate limited (429). Retrying in %s...\n", wait.Round(time.Second))
+
+		if retries >= maxRetry {
+			return body, status, fmt.Errorf("rate limited (429): retry limit reached after %d attempts — try again after %s", retries, wait.Round(time.Second))
+		}
+		if maxTimer > 0 && cumulativeWait+wait > maxTimer {
+			return body, status, fmt.Errorf("rate limited (429): retry wait of %s would exceed max-retry-timer of %s — try again after %s", (cumulativeWait + wait).Round(time.Second), maxTimer.Round(time.Second), wait.Round(time.Second))
+		}
+
+		fmt.Fprintf(os.Stderr, "Rate limited (429). Retrying in %s (attempt %d/%d)...\n", wait.Round(time.Second), retries+1, maxRetry)
 		time.Sleep(wait)
+		cumulativeWait += wait
 		body, status, headers, err = doOnce(req)
 	}
 

internal/config/config.go

@@ -13,11 +13,20 @@ var (
 	orgID          string // UUID format
 	orgIDBase64    string // base64 Webex format
 	TokenRefresher func() (string, error)
+
+	maxRetry      int // max number of 429 retries (0 = no retries)
+	maxRetryTimer int // max total seconds allowed across all 429 waits (0 = unlimited)
 )
 
 func SetToken(t string) { token = t }
 func Token() string      { return token }
 
+func SetMaxRetry(n int)  { maxRetry = n }
+func MaxRetry() int      { return maxRetry }
+
+func SetMaxRetryTimer(secs int) { maxRetryTimer = secs }
+func MaxRetryTimer() int        { return maxRetryTimer }
+
 func SetDebug(d bool) { debug = d }
 func Debug() bool     { return debug }