expose additional error response properties in the exception

Author: lbalmaceda

README.md

@@ -526,7 +526,7 @@ If you need to handle different error scenarios you need to catch first `APIExce
 
 The APIExplorer includes a list of response messages for each endpoint. You can get a clue of what went wrong by asking the Http status code: `exception.getStatusCode()`. i.e. a `status_code=403` would mean that the token has an insufficient scope.
 
-An error code will be included to categorize the type of error, you can get it by calling `exception.getError()`. If you want to see a user friendly description of what happened and why the request is failing check the `exception.getDescription()`.
+An error code will be included to categorize the type of error, you can get it by calling `exception.getError()`. If you want to see a user friendly description of what happened and why the request is failing check the `exception.getDescription()`. Finally, if the error response includes additional properties they can be obtained by calling `exception.getValue("{THE_KEY}")`.
 
 
 ```

src/main/java/com/auth0/exception/APIException.java

@@ -1,5 +1,6 @@
 package com.auth0.exception;
 
+import java.util.Collections;
 import java.util.Map;
 
 /**
@@ -21,6 +22,7 @@ public class APIException extends Auth0Exception {
     private String error;
     private String description;
     private int statusCode;
+    private Map<String, Object> values;
 
     public APIException(String payload, int statusCode, Throwable cause) {
         super(createMessage(payload, statusCode), cause);
@@ -30,6 +32,7 @@ public APIException(String payload, int statusCode, Throwable cause) {
 
     public APIException(Map<String, Object> values, int statusCode) {
         super(createMessage(obtainExceptionMessage(values), statusCode));
+        this.values = Collections.unmodifiableMap(values);
         this.error = obtainExceptionError(values);
         this.description = obtainExceptionMessage(values);
         this.statusCode = statusCode;
@@ -55,6 +58,19 @@ public String getError() {
         return error;
     }
 
+    /**
+     * Returns a value from the error map, if any.
+     *
+     * @param key key of the value to return
+     * @return the value if found or null
+     */
+    public Object getValue(String key) {
+        if (values == null) {
+            return null;
+        }
+        return values.get(key);
+    }
+
     /**
      * Getter for the exception user friendly description of why the request failed.
      * i.e. the description may say which query parameters are valid for that endpoint.
@@ -75,9 +91,9 @@ private static String obtainExceptionMessage(Map<String, Object> values) {
         }
         if (values.containsKey("description")) {
             Object description = values.get("description");
-            if(description instanceof String) {
+            if (description instanceof String) {
                 return (String) description;
-            } else{
+            } else {
                 PasswordStrengthErrorParser policy = new PasswordStrengthErrorParser((Map<String, Object>) description);
                 return policy.getDescription();
             }

src/test/java/com/auth0/client/MockServer.java

@@ -23,6 +23,7 @@ public class MockServer {
     public static final String AUTH_ERROR_WITH_ERROR_DESCRIPTION = "src/test/resources/auth/error_with_error_description.json";
     public static final String AUTH_ERROR_WITH_ERROR = "src/test/resources/auth/error_with_error.json";
     public static final String AUTH_ERROR_WITH_DESCRIPTION = "src/test/resources/auth/error_with_description.json";
+    public static final String AUTH_ERROR_WITH_DESCRIPTION_AND_EXTRA_PROPERTIES = "src/test/resources/auth/error_with_description_and_extra_properties.json";
     public static final String AUTH_ERROR_PLAINTEXT = "src/test/resources/auth/error_plaintext.json";
     public static final String MGMT_ERROR_WITH_MESSAGE = "src/test/resources/mgmt/error_with_message.json";
     public static final String MGMT_CLIENT_GRANTS_LIST = "src/test/resources/mgmt/client_grants_list.json";

src/test/java/com/auth0/net/CustomRequestTest.java

@@ -1,8 +1,8 @@
 package com.auth0.net;
 
 import com.auth0.client.MockServer;
-import com.auth0.exception.Auth0Exception;
 import com.auth0.exception.APIException;
+import com.auth0.exception.Auth0Exception;
 import com.auth0.json.auth.TokenHolder;
 import com.fasterxml.jackson.core.JsonParseException;
 import com.fasterxml.jackson.core.JsonProcessingException;
@@ -214,6 +214,29 @@ public void shouldParseJSONErrorResponseWithError() throws Exception {
         assertThat(authException.getStatusCode(), is(400));
     }
 
+    @Test
+    public void shouldParseJSONErrorResponseWithDescriptionAndExtraProperties() throws Exception {
+        CustomRequest<List> request = new CustomRequest<>(client, server.getBaseUrl(), "GET", listType);
+        server.jsonResponse(AUTH_ERROR_WITH_DESCRIPTION_AND_EXTRA_PROPERTIES, 400);
+        Exception exception = null;
+        try {
+            request.execute();
+            server.takeRequest();
+        } catch (Exception e) {
+            exception = e;
+        }
+        assertThat(exception, is(notNullValue()));
+        assertThat(exception, is(instanceOf(APIException.class)));
+        assertThat(exception.getCause(), is(nullValue()));
+        assertThat(exception.getMessage(), is("Request failed with status code 400: Multifactor authentication required"));
+        APIException authException = (APIException) exception;
+        assertThat(authException.getDescription(), is("Multifactor authentication required"));
+        assertThat(authException.getError(), is("mfa_required"));
+        assertThat(authException.getValue("mfa_token"), is("Fe26...Ha"));
+        assertThat(authException.getValue("non_existing_key"), is(nullValue()));
+        assertThat(authException.getStatusCode(), is(400));
+    }
+
     @Test
     public void shouldParseJSONErrorResponseWithDescription() throws Exception {
         CustomRequest<List> request = new CustomRequest<>(client, server.getBaseUrl(), "GET", listType);

src/test/resources/auth/error_with_description_and_extra_properties.json

@@ -0,0 +1,5 @@
+{
+  "error": "mfa_required",
+  "error_description": "Multifactor authentication required",
+  "mfa_token": "Fe26...Ha"
+}