Expose typed ErrorCode on ApiException and Error alongside raw code

Author: laurentpellegrino

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+- Typed error codes: `ApiException#getErrorCode()` (and `Error#getErrorCode()`) now return a strongly typed `ErrorCode` enum in addition to the raw string `code`, allowing callers to branch on error conditions without string matching. Unrecognized codes return `null` while the raw code remains available.
 - Automatic retries with exponential backoff for transient network errors and 5xx server responses, configurable via `IpregistryConfig` (`retryMaxAttempts`, `retryInterval`, `retryOnServerError`, `retryOnTooManyRequests`). Retries on 429 Too Many Requests are disabled by default and honor the `Retry-After` header when enabled.
 - `IpregistryClient` now implements `Closeable` to release the underlying HTTP connection pool.
 

README.md

@@ -165,6 +165,23 @@ Main subtypes are _ApiException_ and _ClientException_.
 
 Exceptions of type _ApiException_ include a code field that maps to the one described in the [Ipregistry documentation](https://ipregistry.co/docs/errors).
 
+In addition to the raw string `code`, an _ApiException_ exposes a typed `ErrorCode` via `getErrorCode()`, so you can branch on error conditions without string matching:
+
+```java
+try {
+    IpInfo info = ipregistry.lookup("8.8.8.8");
+} catch (ApiException e) {
+    ErrorCode code = e.getErrorCode(); // null if the raw code is not recognized
+    if (code == ErrorCode.INSUFFICIENT_CREDITS) {
+        // handle exhausted credits
+    } else if (code == ErrorCode.TOO_MANY_REQUESTS) {
+        // handle rate limiting
+    }
+} catch (ClientException e) {
+    // handle client-side/network error
+}
+```
+
 ## Filtering bots
 
 You might want to prevent Ipregistry API calls for crawlers or bots browsing your pages. 

src/main/java/co/ipregistry/api/client/exceptions/ApiException.java

@@ -16,6 +16,7 @@
 
 package co.ipregistry.api.client.exceptions;
 
+import co.ipregistry.api.client.model.error.ErrorCode;
 import lombok.Getter;
 
 
@@ -26,10 +27,16 @@
 public class ApiException extends IpregistryException {
 
     /**
-     * The API exception code.
+     * The raw API exception code as returned by the API.
      */
     private final String code;
 
+    /**
+     * The typed API error code, or {@code null} when {@link #code} does not match any known
+     * {@link ErrorCode} (for instance a code introduced after this client release).
+     */
+    private final ErrorCode errorCode;
+
     /**
      * The API exception message.
      */
@@ -44,15 +51,16 @@ public class ApiException extends IpregistryException {
     /**
      * Creates a new instance.
      *
-     * @param errorCode an error code as described in our docs.
+     * @param code an error code as described in our docs.
      * @param message a message describing the error.
      * @param resolution explanation about how to fix the error.
      *
      * @see <a href="https://ipregistry.co/docs/errors">https://ipregistry.co/docs/errors</a>.
      */
-    public ApiException(final String errorCode, final String message, final String resolution) {
+    public ApiException(final String code, final String message, final String resolution) {
         super(message);
-        this.code = errorCode;
+        this.code = code;
+        this.errorCode = ErrorCode.fromCode(code);
         this.message = message;
         this.resolution = resolution;
     }

src/main/java/co/ipregistry/api/client/model/error/Error.java

@@ -60,4 +60,14 @@ public Error() {
     @JsonProperty("resolution")
     private String resolution;
 
+    /**
+     * Returns the typed {@link ErrorCode} for this error.
+     *
+     * @return the {@link ErrorCode} matching {@link #getCode()}, or {@code null} if the code is
+     * {@code null} or not recognized.
+     */
+    public ErrorCode getErrorCode() {
+        return ErrorCode.fromCode(code);
+    }
+
 }

src/main/java/co/ipregistry/api/client/model/error/ErrorCode.java

@@ -16,6 +16,8 @@
 
 package co.ipregistry.api.client.model.error;
 
+import java.util.Locale;
+
 
 /**
  * Enumerates error codes.
@@ -99,6 +101,26 @@ public enum ErrorCode {
     /**
      * No Autonomous System is currently announcing the specified IP address or IP prefix. This can happen with the Origin AS endpoint.
      */
-    UNKNOWN_ASN
+    UNKNOWN_ASN;
+
+    /**
+     * Returns the {@link ErrorCode} matching the specified raw API error code.
+     *
+     * @param code the raw error code as returned by the API (e.g. {@code "TOO_MANY_REQUESTS"}).
+     * @return the matching {@link ErrorCode}, or {@code null} if {@code code} is {@code null} or
+     * does not correspond to any known error code (for instance a code introduced after this
+     * client release).
+     */
+    public static ErrorCode fromCode(final String code) {
+        if (code == null) {
+            return null;
+        }
+
+        try {
+            return ErrorCode.valueOf(code.trim().toUpperCase(Locale.ROOT));
+        } catch (final IllegalArgumentException e) {
+            return null;
+        }
+    }
 
 }

src/test/java/co/ipregistry/api/client/exceptions/ApiExceptionTest.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2019 Ipregistry (https://ipregistry.co).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package co.ipregistry.api.client.exceptions;
+
+import co.ipregistry.api.client.model.error.ErrorCode;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+class ApiExceptionTest {
+
+    @Test
+    void testExposesTypedErrorCodeForKnownCode() {
+        final ApiException exception =
+                new ApiException("INSUFFICIENT_CREDITS", "No credits left", "Buy credits");
+
+        Assertions.assertEquals("INSUFFICIENT_CREDITS", exception.getCode());
+        Assertions.assertEquals(ErrorCode.INSUFFICIENT_CREDITS, exception.getErrorCode());
+    }
+
+    @Test
+    void testKeepsRawCodeButNullTypedCodeForUnknownCode() {
+        final ApiException exception =
+                new ApiException("A_BRAND_NEW_CODE", "message", "resolution");
+
+        Assertions.assertEquals("A_BRAND_NEW_CODE", exception.getCode());
+        Assertions.assertNull(exception.getErrorCode());
+    }
+
+    @Test
+    void testSubclassesInheritTypedErrorCode() {
+        final ApiException exception =
+                new IpInfoException("TOO_MANY_REQUESTS", "Slow down", "Retry later");
+
+        Assertions.assertEquals(ErrorCode.TOO_MANY_REQUESTS, exception.getErrorCode());
+    }
+
+}

src/test/java/co/ipregistry/api/client/model/error/ErrorCodeTest.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2019 Ipregistry (https://ipregistry.co).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package co.ipregistry.api.client.model.error;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+class ErrorCodeTest {
+
+    @Test
+    void testFromCodeMapsKnownCodes() {
+        Assertions.assertEquals(ErrorCode.TOO_MANY_REQUESTS, ErrorCode.fromCode("TOO_MANY_REQUESTS"));
+        Assertions.assertEquals(ErrorCode.INVALID_API_KEY, ErrorCode.fromCode("INVALID_API_KEY"));
+        Assertions.assertEquals(ErrorCode.INSUFFICIENT_CREDITS, ErrorCode.fromCode("INSUFFICIENT_CREDITS"));
+    }
+
+    @Test
+    void testFromCodeIsCaseInsensitiveAndTrimmed() {
+        Assertions.assertEquals(ErrorCode.BAD_REQUEST, ErrorCode.fromCode("  bad_request  "));
+    }
+
+    @Test
+    void testFromCodeReturnsNullForUnknownCode() {
+        Assertions.assertNull(ErrorCode.fromCode("A_BRAND_NEW_CODE"));
+        Assertions.assertNull(ErrorCode.fromCode(""));
+    }
+
+    @Test
+    void testFromCodeReturnsNullForNull() {
+        Assertions.assertNull(ErrorCode.fromCode(null));
+    }
+
+}