Error Code Reference

The Entrupy Android SDK uses defined error codes to communicate issues that occur during operations. Understanding these error codes is important for robust error handling and providing appropriate feedback to your users.

1. EntrupyErrorCode

Errors originating from the SDK are delivered through callback methods, providing a numeric error code and a textual description. The EntrupyErrorCode object defines the standard error codes:

import android.util.Log
import com.entrupy.sdk.app.EntrupyApp
import com.entrupy.sdk.listeners.CaptureCallback
import com.entrupy.sdk.listeners.EntrupyErrorCode
import com.entrupy.sdk.listeners.SdkLoginCallback

// Error codes are delivered through SDK callback methods.
// For example, CaptureCallback.onCaptureError receives an errorCode and description:
entrupyApp.startCapture(
    configMetadata = metadata,
    callback = object : CaptureCallback {
        override fun onCaptureStarted() {
            Log.d("Entrupy", "Capture started")
        }

        override fun onCaptureError(errorCode: Int, description: String) {
            when (errorCode) {
                EntrupyErrorCode.UNAUTHORIZED_ACCESS -> {
                    Log.e("Entrupy", "Token expired or invalid. Re-authorize the user.")
                }
                EntrupyErrorCode.SDK_NOT_INITIALIZED -> {
                    Log.e("Entrupy", "Call EntrupyApp.init(application) first.")
                }
                EntrupyErrorCode.NO_MATCHING_CONFIG -> {
                    Log.e("Entrupy", "No config found for the provided metadata.")
                }
                EntrupyErrorCode.MISSING_METADATA_KEY -> {
                    Log.e("Entrupy", "A required metadata key is missing.")
                }
                else -> {
                    Log.e("Entrupy", "Capture error $errorCode: $description")
                }
            }
        }
    }
)

// Similarly, SdkLoginCallback.onLoginError receives error codes during authorization:
entrupyApp.loginUser(
    signedRequest = signedRequestFromBackend,
    callback = object : SdkLoginCallback {
        override fun onLoginStarted() {
            // Login started.
        }

        override fun onLoginSuccess(expirationTime: Long) {
            // Login succeeded.
        }

        override fun onLoginError(
            errorCode: Int,
            description: String,
            localizedDescription: String
        ) {
            when (errorCode) {
                EntrupyErrorCode.UNAUTHORIZED_ACCESS -> {
                    // Re-authorize the user.
                }
                EntrupyErrorCode.FORBIDDEN -> {
                    // Check package name registration.
                }
                EntrupyErrorCode.TOO_MANY_REQUESTS -> {
                    // Retry with backoff.
                }
                else -> {
                    Log.e("Entrupy", "Login error $errorCode: $localizedDescription")
                }
            }
        }
    }
)

2. Error Code Table

Code	Constant	Description	Handling
0	UNKNOWN_ERROR	An unknown error occurred.	Log details and report to Entrupy support if reproducible.
400	BAD_REQUEST	Incorrect parameters or malformed request.	Review SDK call parameters. Check that all required metadata keys are provided.
401	UNAUTHORIZED_ACCESS	Token expired, revoked, or invalid.	Trigger re-authorization flow. See Session & Token Lifecycle.
403	FORBIDDEN	Package name not registered, or signed request reuse.	Verify your app's package name is registered with Entrupy. Ensure each login uses a freshly signed request.
404	NOT_FOUND	Requested resource not found.	Verify the Entrupy ID or resource identifier is correct.
429	TOO_MANY_REQUESTS	Rate limit reached.	Implement retry with exponential backoff. See API Rate Limits.
500	INTERNAL_SERVER_ERROR	Server-side error at Entrupy.	Advise the user to try again later. Report to Entrupy support if persistent.
503	SERVICE_UNAVAILABLE	Entrupy servers temporarily unavailable.	Retry after a delay.
1001	SEARCH_ITEM_FOUND	Internal — search found a matching item.	Internal SDK code. No developer action needed.
1002	SEARCH_ITEM_NOT_FOUND	Internal — search did not find a matching item.	Internal SDK code. No developer action needed.
2001	NO_MATCHING_CONFIG	No matching configuration for the provided metadata.	Verify METADATA_KEY_BRAND, METADATA_KEY_ITEM_TYPE, and other metadata values.
2002	SDK_NOT_INITIALIZED	SDK was not initialized before use.	Call EntrupyApp.init(application) in your Application.onCreate().
2003	CONFIGURATION_FETCH_ERROR	Failed to fetch SDK configuration.	Check network connectivity. Retry the operation.
2004	MISSING_METADATA_KEY	A required metadata key is missing.	Ensure all required keys are provided in ConfigMetadata. See Performing an Authentication.

3. Throwable Extension

The SDK provides a convenience extension to convert exceptions to Entrupy error codes:

import com.entrupy.sdk.listeners.toEntrupyErrorCode

try {
    // SDK operation
} catch (e: Exception) {
    val code = e.toEntrupyErrorCode()
    Log.e("Entrupy", "Operation failed with code: $code")
}

4. CatalogError

Catalog-related errors are reported through the SdkEventListener interface. Set the event listener on the EntrupyApp instance:

import com.entrupy.sdk.app.EntrupyApp
import com.entrupy.sdk.listeners.SdkEventListener
import com.entrupy.sdk.listeners.CatalogError
import com.entrupy.sdk.listeners.CatalogErrorCode

EntrupyApp.sharedInstance().eventListener = object : SdkEventListener {
    override fun onCatalogError(error: CatalogError) {
        when (error.code) {
            CatalogErrorCode.CATEGORIES_LOAD_FAILED -> {
                Log.e("Catalog", "Failed to load categories: ${error.message}")
            }
            CatalogErrorCode.CATEGORIES_EMPTY -> {
                Log.w("Catalog", "No categories available: ${error.message}")
            }
            CatalogErrorCode.BRANDS_LOAD_FAILED -> {
                Log.e("Catalog", "Failed to load brands: ${error.message}")
            }
            CatalogErrorCode.BRANDS_EMPTY -> {
                Log.w("Catalog", "No brands available: ${error.message}")
            }
        }
    }
}

4.1 CatalogErrorCode Values

Code	Description
CATEGORIES_LOAD_FAILED	Failed to load product categories from the server.
CATEGORIES_EMPTY	Categories loaded but the list is empty.
BRANDS_LOAD_FAILED	Failed to load brands for a category.
BRANDS_EMPTY	Brands loaded but the list is empty for the selected category.

5. Error Handling Strategy

A robust error handling strategy should include:

1. Identify the error using the numeric code or EntrupyErrorCode constants.
2. Log comprehensive details — error code, description, and context (user ID, item ID, operation) — to your analytics system.
3. Display user-friendly messages — use the description parameter for end-user feedback when appropriate.
4. Implement specific recovery actions:
   • UNAUTHORIZED_ACCESS: Trigger re-login flow.
   • TOO_MANY_REQUESTS: Retry with exponential backoff.
   • SDK_NOT_INITIALIZED: Verify initialization in Application.onCreate().
   • MISSING_METADATA_KEY: Check required metadata before calling startCapture().
5. Implement retry mechanisms for transient errors (timeouts, rate limits, service unavailability) with exponential backoff.

Next Steps

• Review the Session & Token Lifecycle for handling authorization errors.
• Implement error handling in your CaptureCallback and SdkLoginCallback.
• Set up API Rate Limits handling for backend operations.