Clarify retry wait semantics

Author: alxgsv

ucare/client.go

@@ -42,6 +42,7 @@ type Config struct {
 	UserAgent string
 	// Retry controls automatic retry of throttled (HTTP 429) requests.
 	// When nil (the default), throttled requests fail immediately.
+	// See RetryConfig for REST vs. Upload API differences in MaxWaitSeconds.
 	Retry *RetryConfig
 }
 

ucare/restapi.go

@@ -171,6 +171,8 @@ func (c *restAPIClient) handleResponse(
 		}
 		wait := retryAfter
 		if wait <= 0 {
+			// Without a usable Retry-After from the server, REST retries fall
+			// back to exponential backoff instead of applying MaxWaitSeconds.
 			wait = expBackoff(tries)
 		}
 		select {

ucare/retry.go

@@ -6,9 +6,14 @@ type RetryConfig struct {
 	// MaxRetries is the maximum number of retry attempts.
 	// 0 means no retries even if RetryConfig is set.
 	MaxRetries int
-	// MaxWaitSeconds caps retry waits.
-	// For REST requests, a positive Retry-After above this cap fails fast.
-	// For upload requests, locally computed backoff is clamped to this cap.
+	// MaxWaitSeconds limits retry waits, but the exact behavior depends on
+	// which API returned HTTP 429:
+	//   - REST API: if the server sends a positive Retry-After above this
+	//     value, the request fails fast with ThrottleError instead of retrying.
+	//     Fallback exponential backoff used when Retry-After is absent or
+	//     invalid is not capped by this field.
+	//   - Upload API: locally computed exponential backoff is clamped to this
+	//     value because the upload API does not return Retry-After.
 	// 0 means no cap.
 	MaxWaitSeconds int
 }