feat: add option for throwing exception on non-successful API request (#1019)

Author: childish-sambino

ExampleNet45Project/Program.cs

@@ -26,7 +26,7 @@ private static async Task Main()
             // Retrieve the API key.
             var apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY") ?? configuration["SendGrid:ApiKey"];
 
-            var client = new SendGridClient(HttpClient, apiKey);
+            var client = new SendGridClient(HttpClient, apiKey, httpErrorAsException: true);
 
             // Send a Single Email using the Mail Helper
             var from = new EmailAddress(configuration.GetValue("SendGrid:From", "[email protected]"), "Example User");
@@ -118,8 +118,8 @@ private static async Task Main()
 
             // POST
             var requestBody = @"{
-              'description': 'Suggestions for products our users might like.', 
-              'is_default': false, 
+              'description': 'Suggestions for products our users might like.',
+              'is_default': false,
               'name': 'Magic Products'
             }";
             json = JsonConvert.DeserializeObject<object>(requestBody);
@@ -173,4 +173,4 @@ private static async Task Main()
             }
         }
     }
-}
+}

TROUBLESHOOTING.md

@@ -53,17 +53,78 @@ In the first case SENDGRID_API_KEY is in reference to the name of the environmen
 <a name="error"></a>
 ## Error Messages
 
-To read the error message returned by Twilio SendGrid's API:
+By default if the API returns an error, it doesn't throw an exception, but you can read the error message returned by Twilio SendGrid's API:
 
 ```csharp
 var response = await client.RequestAsync(method: SendGridClient.Method.POST,
-                                                 requestBody: msg.Serialize(),
-                                                 urlPath: "mail/send");
+                                         requestBody: msg.Serialize(),
+                                         urlPath: "mail/send");
 Console.WriteLine(response.StatusCode);
 Console.WriteLine(response.Body.ReadAsStringAsync().Result); // The message will be here
 Console.WriteLine(response.Headers.ToString());
 ```
 
+If you want to throw the exception when the API returns an error, init the SendGridClient with the parameter 'httpErrorAsException' as true:
+
+```csharp
+SendGridClient client = new SendGridClient(apiKey, httpErrorAsException: true);
+```
+
+Then if an error is thrown due to a failed request, a summary of that error along with a link to the appropriate place in the documentation will be sent back as a JSON object in the Exception Message. You can also deserialize the JSON object as a SendGridErrorResponse. Every error status code returned by the API has its own type of exception (BadRequestException, UnauthorizedException, PayloadTooLargeException, SendGridInternalException, etc.). All the possibles status codes and errors are documented [here](https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html).
+
+### EXAMPLES
+
+#### 401 - Unauthorized
+
+```csharp
+SendGridClient client = new SendGridClient("", httpErrorAsException: true);
+
+try
+{
+    var response = await client.RequestAsync(method: SendGridClient.Method.POST,
+                                             requestBody: msg.Serialize(),
+                                             urlPath: "mail/send");
+}
+catch(Exception ex)
+{
+    SendGridErrorResponse errorResponse = JsonConvert.DeserializeObject<SendGridErrorResponse>(ex.Message);
+    Console.WriteLine(ex.Message);
+    //{
+    //  "ErrorHttpStatusCode":401,
+    //  "ErrorReasonPhrase":"Unauthorized",
+    //  "SendGridErrorMessage":"Permission denied, wrong credentials",
+    //  "FieldWithError":null,
+    //  "HelpLink":null
+    //}
+}
+```
+
+#### 400 - Bad Request - From Email Null
+
+```csharp
+var client = new SendGridClient(apiKey, httpErrorAsException: true);
+
+try
+{
+    var from = new EmailAddress("", "Example User"); // From email null
+    var msg = MailHelper.CreateSingleEmail(from, to, subject, plainTextContent, htmlContent);
+
+    var response = await client.SendEmailAsync(msg).ConfigureAwait(false);
+}
+catch (Exception ex)
+{
+    SendGridErrorResponse errorResponse = JsonConvert.DeserializeObject<SendGridErrorResponse>(ex.Message);
+    Console.WriteLine(ex.Message);
+    //{
+    //  "ErrorHttpStatusCode":400,
+    //  "ErrorReasonPhrase":"Bad Request",
+    //  "SendGridErrorMessage":"The from email does not contain a valid address.",
+    //  "FieldWithError":"from.email",
+    //  "HelpLink":"http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.from"
+    //}
+}
+```
+
 <a name="migrating"></a>
 ## Migrating from the v2 API to v3
 
@@ -134,7 +195,7 @@ In our example code, you would change:
 var response = await client.SendEmailAsync(msg);
 ```
 
-to 
+to
 
 ```csharp
 var response = await client.SendEmailAsync(msg).ConfigureAwait(false);

src/SendGrid/BaseClient.cs

@@ -1,4 +1,5 @@
 using Newtonsoft.Json;
+using SendGrid.Helpers.Errors;
 using SendGrid.Helpers.Mail;
 using SendGrid.Helpers.Reliability;
 using System;
@@ -153,6 +154,12 @@ public virtual AuthenticationHeaderValue AddAuthorization(KeyValuePair<string, s
         public virtual async Task<Response> MakeRequest(HttpRequestMessage request, CancellationToken cancellationToken = default(CancellationToken))
         {
             HttpResponseMessage response = await this.client.SendAsync(request, cancellationToken).ConfigureAwait(false);
+
+            if (!response.IsSuccessStatusCode && this.options.HttpErrorAsException)
+            {
+                await ErrorHandler.ThrowException(response).ConfigureAwait(false);
+            }
+
             return new Response(response.StatusCode, response.Content, response.Headers);
         }
 

src/SendGrid/BaseClientOptions.cs

@@ -45,5 +45,10 @@ public ReliabilitySettings ReliabilitySettings
         /// The Auth header value.
         /// </summary>
         public AuthenticationHeaderValue Auth { get; set; }
+
+        /// <summary>
+        /// Gets or sets a value indicating whether HTTP error responses should be raised as exceptions. Default is false.
+        /// </summary>
+        public bool HttpErrorAsException { get; set; } = false;
     }
 }

src/SendGrid/Helpers/Errors/ErrorHandler.cs

@@ -0,0 +1,154 @@
+using Newtonsoft.Json.Linq;
+using SendGrid.Helpers.Errors.Model;
+using System.Net.Http;
+using System.Threading.Tasks;
+
+namespace SendGrid.Helpers.Errors
+{
+    /// <summary>
+    /// Error handler for requests.
+    /// </summary>
+    public class ErrorHandler
+    {
+        /// <summary>
+        /// Throw the exception based on HttpResponseMessage
+        /// </summary>
+        /// <param name="message">Response Message from API</param>
+        /// <returns>Return the exception. Obs: Exceptions from an Async Void Method Can’t Be Caught with Catch </returns>
+        public static async Task ThrowException(HttpResponseMessage message)
+        {
+            var errorMessage = await ErrorHandler.GetErrorMessage(message).ConfigureAwait(false);
+
+            var errorStatusCode = (int)message.StatusCode;
+
+            switch (errorStatusCode)
+            {
+                // 400 - BAD REQUEST
+                case 400:
+                    throw new BadRequestException(errorMessage);
+
+                // 401 - UNAUTHORIZED
+                case 401:
+                    throw new UnauthorizedException(errorMessage);
+
+                // 403 - FORBIDDEN
+                case 403:
+                    throw new ForbiddenException(errorMessage);
+
+                // 404 - NOT FOUND
+                case 404:
+                    throw new NotFoundException(errorMessage);
+
+                // 405 - METHOD NOT ALLOWED
+                case 405:
+                    throw new MethodNotAllowedException(errorMessage);
+
+                // 413 - PAYLOAD TOO LARGE
+                case 413:
+                    throw new PayloadTooLargeException(errorMessage);
+
+                // 415 - UNSUPPORTED MEDIA TYPE
+                case 415:
+                    throw new UnsupportedMediaTypeException(errorMessage);
+
+                // 429 - TOO MANY REQUESTS
+                case 429:
+                    throw new TooManyRequestsException(errorMessage);
+
+                // 500 - SERVER UNAVAILABLE
+                case 500:
+                    throw new ServerUnavailableException(errorMessage);
+
+                // 503 - SERVICE NOT AVAILABLE
+                case 503:
+                    throw new ServiceNotAvailableException(errorMessage);
+            }
+
+            // 4xx - Error with the request
+            if (errorStatusCode >= 400 && errorStatusCode < 500)
+            {
+                throw new RequestErrorException(errorMessage);
+            }
+
+            // 5xx - Error made by SendGrid
+            if (errorStatusCode >= 500)
+            {
+                throw new SendGridInternalException(errorMessage);
+            }
+
+            throw new BadRequestException(errorMessage);
+        }
+
+        /// <summary>
+        /// Get error based on Response from SendGrid API
+        /// Method taken from the StrongGrid project (https://github.com/Jericho/StrongGrid) with some minor changes. Thanks Jericho (https://github.com/Jericho)
+        /// </summary>
+        /// <param name="message">Response Message from API</param>
+        /// <returns>Return string with the error Status Code and the Message</returns>
+        private static async Task<string> GetErrorMessage(HttpResponseMessage message)
+        {
+            var errorStatusCode = (int)message.StatusCode;
+            var errorReasonPhrase = message.ReasonPhrase;
+
+            string errorValue = null;
+            string fieldValue = null;
+            string helpValue = null;
+
+            if (message.Content != null)
+            {
+                var responseContent = await message.Content.ReadAsStringAsync().ConfigureAwait(false);
+
+                if (!string.IsNullOrEmpty(responseContent))
+                {
+                    try
+                    {
+                        // Check for the presence of property called 'errors'
+                        var jObject = JObject.Parse(responseContent);
+                        var errorsArray = (JArray)jObject["errors"];
+                        if (errorsArray != null && errorsArray.Count > 0)
+                        {
+                            // Get the first error message
+                            errorValue = errorsArray[0]["message"].Value<string>();
+
+                            // Check for the presence of property called 'field'
+                            if (errorsArray[0]["field"] != null)
+                            {
+                                fieldValue = errorsArray[0]["field"].Value<string>();
+                            }
+
+                            // Check for the presence of property called 'help'
+                            if (errorsArray[0]["help"] != null)
+                            {
+                                helpValue = errorsArray[0]["help"].Value<string>();
+                            }
+                        }
+                        else
+                        {
+                            // Check for the presence of property called 'error'
+                            var errorProperty = jObject["error"];
+                            if (errorProperty != null)
+                            {
+                                errorValue = errorProperty.Value<string>();
+                            }
+                        }
+                    }
+                    catch
+                    {
+                        // Intentionally ignore parsing errors to return default error message
+                    }
+                }
+            }
+
+            SendGridErrorResponse errorResponse = new SendGridErrorResponse
+            {
+                ErrorHttpStatusCode = errorStatusCode,
+                ErrorReasonPhrase = errorReasonPhrase,
+                SendGridErrorMessage = errorValue,
+                FieldWithError = fieldValue,
+                HelpLink = helpValue
+            };
+
+            return Newtonsoft.Json.JsonConvert.SerializeObject(errorResponse);
+        }
+    }
+}

src/SendGrid/Helpers/Errors/Model/BadRequestException.cs

@@ -0,0 +1,37 @@
+using System;
+
+namespace SendGrid.Helpers.Errors.Model
+{
+    /// <summary>
+    /// Represents errors with status code 400
+    /// </summary>
+    public class BadRequestException : RequestErrorException
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BadRequestException"/> class.
+        /// </summary>
+        public BadRequestException()
+            : base()
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BadRequestException"/> class with a specified error.
+        /// </summary>
+        /// <param name="message"> The error message that explains the reason for the exception.</param>
+        public BadRequestException(string message)
+                : base(message)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BadRequestException"/> class with a specified error and a reference to the inner exception that is the cause of this exception.
+        /// </summary>
+        /// <param name="message">The error message that explains the reason for the exception.</param>
+        /// <param name="innerException">The exception that is the cause of the current exception, or a null reference  if no inner exception is specified.</param>
+        public BadRequestException(string message, Exception innerException)
+            : base(message, innerException)
+        {
+        }
+    }
+}

src/SendGrid/Helpers/Errors/Model/ForbiddenException.cs

@@ -0,0 +1,37 @@
+using System;
+
+namespace SendGrid.Helpers.Errors.Model
+{
+    /// <summary>
+    /// Represents errors with status code 403
+    /// </summary>
+    public class ForbiddenException : RequestErrorException
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ForbiddenException"/> class.
+        /// </summary>
+        public ForbiddenException()
+            : base()
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ForbiddenException"/> class with a specified error.
+        /// </summary>
+        /// <param name="message"> The error message that explains the reason for the exception.</param>
+        public ForbiddenException(string message)
+                : base(message)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ForbiddenException"/> class with a specified error and a reference to the inner exception that is the cause of this exception.
+        /// </summary>
+        /// <param name="message">The error message that explains the reason for the exception.</param>
+        /// <param name="innerException">The exception that is the cause of the current exception, or a null reference  if no inner exception is specified.</param>
+        public ForbiddenException(string message, Exception innerException)
+            : base(message, innerException)
+        {
+        }
+    }
+}