Add RateLimitException with RetryAfter field.

Author: qimingyuan

Dropbox.Api/DropboxClient.common.cs

@@ -120,7 +120,7 @@ public class HttpException : Exception
         /// <param name="message">The message.</param>
         /// <param name="uri">The request uri.</param>
         /// <param name="inner">The inner.</param>
-        public HttpException(int statusCode, string message = null, Uri uri = null, Exception inner = null)
+        internal HttpException(int statusCode, string message = null, Uri uri = null, Exception inner = null)
             : base(message, inner)
         {
             this.StatusCode = statusCode;
@@ -154,7 +154,7 @@ public class BadInputException : HttpException
         /// </summary>
         /// <param name="message">The message that describes the error.</param>
         /// <param name="uri">The request URI.</param>
-        public BadInputException(string message, Uri uri = null)
+        internal BadInputException(string message, Uri uri = null)
             : base(400, message, uri)
         {
         }
@@ -170,7 +170,7 @@ public partial class AuthException
         /// </summary>
         /// <param name="message">The message that describes the error.</param>
         /// <param name="uri">The request URI</param>
-        [Obsolete("This constructor will be removed soon.")] 
+        [Obsolete("This constructor will be removed soon.")]
         public AuthException(string message, Uri uri = null) : base(null, message)
         {
             this.StatusCode = 401;
@@ -197,23 +197,22 @@ public AuthException(string message, Uri uri = null) : base(null, message)
     }
 
     /// <summary>
-    /// An HTTP Exception that will cause a retry
+    /// An HTTP Exception that will cause a retry due to transient failure. The SDK will perform
+    /// a certain number of retries which is configurable in <see cref="DropboxClient"/>. If the client
+    /// still gets this exception, it's up to the client to decide whether to continue retrying or not.
     /// </summary>
     public class RetryException : HttpException
     {
         /// <summary>
         /// Initializes a new instance of the <see cref="RetryException"/> class.
         /// </summary>
         /// <param name="statusCode">The status code.</param>
-        /// <param name="isRateLimit">if set to <c>true</c> the server responded with
-        /// an error indicating rate limiting.</param>
         /// <param name="message">The message.</param>
         /// <param name="uri">The request URI.</param>
         /// <param name="inner">The inner.</param>
-        public RetryException(int statusCode, bool isRateLimit = false, string message = null, Uri uri = null, Exception inner = null)
+        internal RetryException(int statusCode, string message = null, Uri uri = null, Exception inner = null)
             : base(statusCode, message, uri, inner)
         {
-            this.IsRateLimit = isRateLimit;
         }
 
         /// <summary>
@@ -222,6 +221,48 @@ public RetryException(int statusCode, bool isRateLimit = false, string message =
         /// <value>
         /// <c>true</c> if this response is a rate limit; otherwise, <c>false</c>.
         /// </value>
-        public bool IsRateLimit { get; private set; }
+        [Obsolete("This field will be removed soon. Please catch RateLimitException separately.")]
+        public virtual bool IsRateLimit
+        {
+            get { return false; }
+        }
+    }
+
+    /// <summary>
+    /// An HTTP Exception that will cause a retry due to rate limiting. The SDK will not do auto-retry for
+    /// this type of exception. The client should do proper backoff based on the value of
+    /// <see cref="RateLimitException.RetryAfter"/> field.
+    /// </summary>
+    public class RateLimitException : RetryException
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="RateLimitException"/> class.
+        /// </summary>
+        /// <param name="retryAfter">The time in second which the client should retry after.</param>
+        /// <param name="message">The message.</param>
+        /// <param name="uri">The request URI.</param>
+        /// <param name="inner">The inner.</param>
+        internal RateLimitException(int retryAfter, string message = null, Uri uri = null, Exception inner = null)
+            : base(429, message, uri, inner)
+        {
+            this.RetryAfter = retryAfter;
+        }
+
+        /// <summary>
+        /// Gets the value in second which the client should backoff and retry after.
+        /// </summary>
+        public int RetryAfter { get; private set; }
+
+        /// <summary>
+        /// Gets a value indicating whether this error represents a rate limiting response from the server.
+        /// </summary>
+        /// <value>
+        /// <c>true</c> if this response is a rate limit; otherwise, <c>false</c>.
+        /// </value>
+        [Obsolete("This field will be removed soon.")]
+        public override bool IsRateLimit
+        {
+            get { return true; }
+        }
     }
 }

Dropbox.Api/DropboxRequestHandler.cs

@@ -160,7 +160,7 @@ async Task<TResponse> ITransport.SendUploadRequestAsync<TRequest, TResponse, TEr
             var serializedArg = JsonWriter.Write(request, requestEncoder, true);
             var res = await this.RequestJsonStringWithRetry(host, route, RouteStyle.Upload, serializedArg, body)
                 .ConfigureAwait(false);
-            
+
             if (res.IsError)
             {
                 throw StructuredException<TError>.Decode<ApiException<TError>>(res.ObjectResult, errorDecoder);
@@ -273,16 +273,15 @@ private async Task<Result> RequestJsonStringWithRetry(
                         }
                     }
                 }
-                catch (RetryException re)
+                catch (RateLimitException)
                 {
-                    if (!re.IsRateLimit)
-                    {
-                        // dropbox maps 503 - ServiceUnavailable to be a rate limiting error.
-                        // do not count a rate limiting error as an attempt
-                        attempt++;
-                    }
-
-                    if (attempt > maxRetries)
+                    throw;
+                }
+                catch (RetryException)
+                {
+                    // dropbox maps 503 - ServiceUnavailable to be a rate limiting error.
+                    // do not count a rate limiting error as an attempt
+                    if (++attempt > maxRetries)
                     {
                         throw;
                     }
@@ -306,7 +305,7 @@ private async Task<Result> RequestJsonStringWithRetry(
         /// <returns>The contents of the error field if present, otherwise <paramref name="text" />.</returns>
         private string CheckForError(string text)
         {
-            try 
+            try
             {
                 var obj = JObject.Parse(text);
                 JToken error;
@@ -411,7 +410,11 @@ private async Task<Result> RequestJsonString(
                 }
                 else if ((int)response.StatusCode == 429)
                 {
-                    throw new RetryException(429, uri: uri, isRateLimit: true);
+                    var text = await response.Content.ReadAsStringAsync();
+                    text = this.CheckForError(text);
+                    var retryAfter = response.Headers.GetValues("Retry-After");
+
+                    throw new RateLimitException(int.Parse(retryAfter.First()), message: text, uri: uri);
                 }
                 else if (response.StatusCode == HttpStatusCode.Conflict ||
                     response.StatusCode == HttpStatusCode.Forbidden ||