Package co.ankatech.ankasecure.sdk.exception

Class AnkaSecureSdkException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
co.ankatech.ankasecure.sdk.exception.AnkaSecureSdkException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
DestinationExistsException, Http2RequiredException, StaleSidecarException, StreamIntegrityException, StreamWriteFailedException, TokenRevokedException
public class AnkaSecureSdkException extends RuntimeException
A uniform, localization-ready exception thrown by all public AnkaSecure SDK APIs.

This exception carries HTTP error information returned by a remote service, including status code, response body, and an optional SDK error code. It also allows attaching arbitrary context data for richer diagnostics.

Handling SDK Exceptions

Error Code-Based Handling


 try {
     EncryptResult result = sdk.encrypt("my-key", plaintext);
 } catch (AnkaSecureSdkException e) {
     switch (e.getErrorCode()) {
         case AUTH_FAILED:
             // Re-authenticate and retry
             sdk.authenticateApplication(clientId, clientSecret);
             break;
         case INVALID_KEY:
             // Key not found or expired
             logger.error("Key '{}' is invalid", e.getContext().get("kid"));
             break;
         case RATE_LIMIT_EXCEEDED:
             // Backoff and retry, honoring the server-provided Retry-After hint when present
             Long retryAfterSeconds = e.getRetryAfterSeconds();
             Thread.sleep((retryAfterSeconds != null ? retryAfterSeconds : 1L) * 1000L);
             break;
         default:
             // Generic handling
             logger.error("API error: {} (HTTP {})", e.getMessage(), e.getHttpStatus());
     }
 }

HTTP Status-Based Handling


 try {
     EncryptResult result = sdk.encrypt(kid, plaintext);
 } catch (AnkaSecureSdkException e) {
     if (e.getHttpStatus() == 404) {
         // Key not found for this tenant
         logger.error("Key '{}' does not exist", kid);
     } else if (e.getHttpStatus() >= 500) {
         // Server error, implement retry logic
         retryWithBackoff(() -> sdk.encrypt(kid, plaintext));
     }
 }

Contextual Information

Use getContext() for detailed diagnostics: 


 try {
     DecryptResult result = sdk.decrypt(jwe);
 } catch (AnkaSecureSdkException e) {
     Map<String, String> context = e.getContext();
     logger.error("Decryption failed for kid={}, algorithm={}, status={}",
         context.get("kid"),
         context.get("algorithm"),
         e.getHttpStatus());
 }

Base Type for SDK-Thrown Exceptions

This is the documented base type of the SDK's public exception hierarchy. More specific client-side conditions are modelled as subclasses (for example DestinationExistsException, StreamIntegrityException, StaleSidecarException), so a single catch (AnkaSecureSdkException e) catches every failure the SDK raises. For a purely client-side subclass (no HTTP round-trip), getHttpStatus() is 0, getResponseBody() is null, and getContext() is empty.

Since:
1.0.0
See Also:

  • Constructor Details

    • AnkaSecureSdkException

      public AnkaSecureSdkException(String message, int httpStatus, String responseBody, Throwable cause, Map<String,String> context)
      Constructs a new SDK exception with the specified message, HTTP status, response body, cause, and context. The error code is initialized to SdkErrorCode.UNKNOWN and retryAfterSeconds to null.
      Parameters:
      message - the detail message for this exception
      httpStatus - the HTTP status code associated with this error
      responseBody - the body of the HTTP response returned by the remote service
      cause - the underlying cause of this exception (may be null)
      context - additional context information as key-value pairs
      Since:
      1.0.0

    • AnkaSecureSdkException

      public AnkaSecureSdkException(String message, int httpStatus, String responseBody, Throwable cause, Map<String,String> context, SdkErrorCode errorCode, Long retryAfterSeconds)
      Constructs a new SDK exception with the specified message, HTTP status, response body, cause, context, a specific SDK error code, and the server-provided Retry-After hint.
      Parameters:
      message - the detail message for this exception
      httpStatus - the HTTP status code associated with this error
      responseBody - the body of the HTTP response returned by the remote service
      cause - the underlying cause of this exception (may be null)
      context - additional context information as key-value pairs
      errorCode - the SdkErrorCode representing the specific error condition
      retryAfterSeconds - the server-provided Retry-After header value in integer seconds, or null when the server did not send one
      Since:
      1.0.0

  • Method Details

    • getHttpStatus

      public int getHttpStatus()
      Returns the HTTP status code returned by the remote service.
      Returns:
      the HTTP status code

    • getResponseBody

      public String getResponseBody()
      Returns the full response body returned by the remote service.
      Returns:
      the HTTP response body as a string

    • getContext

      public Map<String,String> getContext()
      Returns additional context information provided with this exception.
      Returns:
      an unmodifiable map of context key-value pairs

    • getErrorCode

      public SdkErrorCode getErrorCode()
      Returns the specific SDK error code categorizing this failure.
      Returns:
      the SdkErrorCode for this exception

    • getRetryAfterSeconds

      public Long getRetryAfterSeconds()
      Returns the server-provided Retry-After hint, in integer seconds.

      The platform emits this header while a server-side circuit breaker toward an upstream dependency is open (typically alongside HTTP 502/504). Callers implementing retry logic should wait at least this many seconds before the next attempt.

      Returns:
      the Retry-After value in seconds, or null when the server did not provide one