Error Code Reference

The Entrupy iOS SDK uses a set of defined error codes (EntrupyErrorCode) to communicate various issues that can occur during its operations. Understanding these error codes is important for robust error handling and providing appropriate feedback to your users.

This document lists the common error codes, their descriptions, and potential causes or handling strategies.

EntrupyErrorCode Enum

Errors originating from the Entrupy SDK are typically delivered through delegate methods, often providing an EntrupyErrorCode enum value, a textual description, and a localized description suitable for display to the user.

// Example of how an error code might be received in a delegate
/*
func didSomeOperationFailWithError(_ errorCode: EntrupyErrorCode, description: String, localizedDescription: String) {
    print("Operation failed! Code: \(errorCode.rawValue), Description: \(description)")
    showAlert(title: "Error \(errorCode.rawValue)", message: localizedDescription)

    switch errorCode {
    case .ErrorCodeOfflineAccess:
        // Specific handling for offline access
        break
    case .ErrorCodeUnauthorizedAccess:
        // Specific handling for unauthorized access (e.g., prompt for re-login)
        break
    // ... handle other specific error codes ...
    default:
        // Generic handling
        break
    }
}
*/

Common Error Codes

The following table lists common EntrupyErrorCode values, based on Section 15 of sdk-v1-legacy.md. Always refer to the latest SDK documentation or header files for the most current and complete list.

Error Code (EntrupyErrorCode)	Description	Potential Causes & Handling Notes
ErrorCodeOfflineAccess	Could not connect to the Internet.	Device has no active internet connection (Wi-Fi or cellular). Advise user to check connection. Implement reachability checks before SDK operations.
ErrorCodeBadRequest	Incorrect headers, missing/incorrect parameters.	Usually indicates an issue with how the SDK call was made or an unexpected server response. Ensure all required parameters are correctly provided. May require debugging SDK integration or contacting Entrupy support if persistent.
ErrorCodeUnauthorizedAccess	The authorization token is expired, revoked, request is malformed, or invalid for other reasons.	Token expired: Implement re-authorization flow (see Session & Token Lifecycle Management). Malformed request: Review backend signing process. Invalid for other reasons: May need Entrupy support.
ErrorCodeForbiddenError	The bundle ID is invalid, or re-using signed authorization requests.	Bundle ID Mismatch: Ensure your app's bundle ID is correctly registered with Entrupy. Re-using signed requests: Ensure each login attempt uses a freshly signed request from your backend.
ErrorCodeInternalServerError	An error occurred with the Entrupy Server.	This is a server-side issue at Entrupy. Advise user to try again later. If persistent, report to Entrupy support with context.
ErrorCodeRequestTimeoutError	The request timed out due to a client-side delay.	Poor network conditions on the client-side, or the SDK operation took too long to complete locally before sending/receiving. Advise user to try again, possibly on a better connection.
ErrorCodeServerTimeoutError	The Entrupy server timed out.	The Entrupy servers took too long to respond to a request. Advise user to try again later.
ErrorCodeTooManyRequests	The rate limit has been reached.	Application or user is making too many requests in a short period. Implement retry logic with backoff (e.g., wait 1 second as suggested in sdk-v1-legacy.md, then retry). Check API documentation for specific rate limits.
ErrorCodeImageUploadError	The item photos submitted by the user failed to upload. The most common reason is packet loss on lossy networks.	Poor or unstable network connection during image upload. Advise user to try again on a more stable connection. SDK might have internal retries, but persistent failures point to network issues.
ErrorCodeUserDeniedPermissions	The user denied required permissions. For example, camera access.	User tapped "Don't Allow" when prompted for camera or other necessary permissions. Guide user to app settings to enable required permissions.
ErrorCodeUnknownError	An unknown error occurred.	An unexpected error not covered by other codes. Log detailed information and report to Entrupy support if reproducible.

(This list is based on sdk-v1-legacy.md. Additional or different error codes may exist in the current version of the SDK. Always consult the SDK's official documentation or header files for the definitive list.)

Error Handling Strategy

A robust error handling strategy should include:

1. Identify the Error: Use the errorCode to determine the type of error.
2. Log Comprehensive Details: Log the errorCode, description, localizedDescription, and any relevant context (e.g., user ID, item ID, operation being attempted) to your analytics or logging system. This is invaluable for debugging.
3. User-Friendly Messages: Display the localizedDescription to the user when appropriate, as it's intended for end-user consumption. For some errors, you might want to show a more tailored message.
4. Specific Recovery Actions: For certain errors, specific recovery actions can be suggested or automated:
   • ErrorCodeOfflineAccess: Prompt to check internet.
   • ErrorCodeUnauthorizedAccess: Trigger re-login/re-authorization flow.
   • ErrorCodeUserDeniedPermissions: Guide to settings.
   • ErrorCodeTooManyRequests: Implement retry with backoff.
5. General Fallback: For unexpected or server-side errors, a general message like "An error occurred. Please try again later." might be appropriate.
6. Retry Mechanisms: For transient errors (timeouts, rate limits, some network issues), implement a retry mechanism with an exponential backoff strategy to avoid overwhelming the server or a poor user experience.

By handling these error codes gracefully, you can improve the resilience of your Entrupy SDK integration and provide better support to your users when issues arise.

Next Steps

• Review the delegate protocols for various SDK operations (e.g., EntrupyLoginDelegate, EntrupyCaptureDelegate, EntrupySearchDelegate, EntrupyFlagDelegate) to see how errors are reported for each.
• Implement error handling in all your delegate methods that can receive error callbacks.
• Refer to individual feature guides for context-specific error scenarios.