Skip to main content

​
EncoreError

Represents the errors that can occur when using the Encore SDK. Handle these errors gracefully to provide a good user experience.

​
Definition

public enum EncoreError: Error, LocalizedError {
  case notInitialized
  case userIdNotAvailable
  case networkError(Error)
  case decodingError(Error)
  case invalidURL
  case unknown
  case serverResponse(String)
  case httpError(statusCode: Int, message: String?)
  case apiError(code: String?, message: String)
}

​
Error Cases

ErrorAssociated ValuesDescription
.notInitializedNoneSDK not configured. Call Encore.shared.configure(apiKey:) at launch.
.userIdNotAvailableNoneUser ID required but missing. Rare - SDK auto-generates anonymous IDs.
.networkErrorErrorNetwork connection issue (no internet, timeout, connection failed).
.decodingErrorErrorResponse parsing failed (unexpected format or structure).
.invalidURLNoneURL construction failed (malformed API endpoint).
.unknownNoneUnexpected system error with no specific cause identified.
.serverResponseStringServer returned an error response with a message.
.httpErrorstatusCode: Int, message: String?HTTP status error (4xx/5xx responses from server).
.apiErrorcode: String?, message: StringAPI returned an error response (validation or business logic error).

​
Usage

Encore.placement()
  .onNotGranted { reason in
    if case .error(let encoreError) = reason {
      switch encoreError {
      case .notInitialized:
        print("SDK not configured")
      case .networkError(let underlyingError):
        print("Network error: \(underlyingError.localizedDescription)")
      case .apiError(let code, let message):
        print("API error (\(code ?? "unknown")): \(message)")
      default:
        print("Error: \(encoreError.localizedDescription)")
      }
    }
  }
  .show()

​
Error Handling Best Practices

​
1. Always Handle Errors Gracefully

Encore.placement()
  .onNotGranted { reason in
    if case .error(let error) = reason {
      // Log error for debugging
      logError(error)
      
      // Show user-friendly message
      showAlert("Unable to load offers. Please try again later.")
    }
    
    // Always allow user to proceed
    proceedWithOriginalAction()
  }
  .show()

​
2. Distinguish Between User Actions and Errors

Encore.placement()
  .onNotGranted { reason in
    switch reason {
    case .error(let error):
      // This is a system error - log it
      analytics.track("offer_system_error", error: error)
      logError(error)
    default:
      // This is user choice - track it
      analytics.track("offer_user_declined")
    }
    proceedWithOriginalAction()
  }
  .show()

​
3. Provide Fallback Behavior

Encore.placement()
  .onGranted { entitlement in
    applyEntitlement(entitlement)
  }
  .onNotGranted { reason in
    // Error or user declined - proceed with fallback
    proceedWithOriginalAction()
  }
  .show()
Never block user actions due to SDK errors. Always provide a fallback path that allows users to complete their intended action.
Most errors are rare. The most common “error” is actually the user declining an offer, which is normal behavior and should be handled as such through NotGrantedReason, not as an error.