Error Handling

This guide covers how errors are surfaced in the Flutter SDK and how to respond to them.


Overview

Errors in the SDK fall into two categories:

CategoryWhen It Occurs
Initialization errorsBefore playback begins, invalid OTP, network failure, DRM license rejection
Playback errorsDuring active playback, network drop, CDN failure, stream corruption

How Errors Reach Flutter

The native player automatically shows a built-in error screen when a playback failure occurs. The error screen displays a message and a Retry button, which reloads the player with the last-used params.


InkryptPlayerError

In the current SDK version, errors are transmitted from the native layer to the Dart layer via the MethodChannel, but the public error API is not exposed on InkryptVideoPlayerController.

When the error stream becomes available, errors will be delivered as InkryptPlayerError objects.

Properties

PropertyTypeDescription
codeint?Numeric error code from the DRM license server. null for nearly all errors
messageString?Error message string — the primary signal for identifying the error type

Understanding code

code is null for the vast majority of errors, including all internal SDK failures (invalid configuration, network issues, DRM failures, player errors). The only case where code is non-nil is when the Inkrypt license server returns a JSON response containing a numeric "code" field.

Use message as your primary signal.


iOS Error Reference

On iOS, errors originate from the FairPlay DRM system, AVFoundation, and the Inkrypt iOS SDK. The primary signal is InkryptPlayerError.message.

code is null for nearly all iOS errors. It is only set when the Inkrypt FairPlay license server returns a JSON response containing a numeric "code" field.

For the complete list of iOS error messages and their meaning, see the iOS Errors Guide.

iOS Error Messages Quick Reference

messageMeaning
"init_error_fps_ce"Failed to fetch the FairPlay certificate — network issue or invalid Video ID
"init_error_video_data"Failed to fetch video metadata — network issue or invalid Video ID
"Failed to infer Video Manifest URL"Metadata retrieved but no valid stream URL could be constructed
"One-Time-Password has not been set"OTP is missing from InkPlayerParams
"Please specify an URL for the Video Playback"No playback URL available
"Failed to get CKC: ..."FairPlay license exchange failed; suffix contains the underlying error
AVPlayer error stringNative AVPlayerItem failure — OS-level error description
License server stringMessage returned directly from the Inkrypt license server

Android Error Reference

On Android, errors originate from the Widevine DRM system, ExoPlayer/Media3, and the Inkrypt Android SDK. The primary signal is InkryptPlayerError.code.

Android errors are split into two groups:

  • Inkrypt Errors: SDK-level codes for authentication, security, and API failures
  • Media Errors: codes from the ExoPlayer/Media3 engine

For the complete error code tables with full descriptions, see the Android Errors Guide.

Inkrypt Error Codes Quick Reference

codeNameMeaning
20Network ErrorNo connectivity or request failed
21SSL ErrorSSL/TLS failure during a network request
30Resource Not FoundRequested resource not found on server
9101API ErrorServer returned an error response
9102UnauthenticatedVideo ID or OTP is incorrect
9104Missing OTPOTP was not provided
9201Developer Mode EnabledDevice has Developer Options on — use tolerateDeveloperMode: true to bypass during development
9202USB Debugging EnabledADB debugging is on — same resolution as 9201
9301Session Forced ExpirationServer forcibly ended the session (OTP revoked or account deactivated)
9311Invalid OTPOTP rejected by the server (HTTP 401)
9312Expired OTPOTP has expired (HTTP 403) — regenerate a fresh OTP

Media Error Codes Quick Reference

code rangeCategory
1000–1004General player errors
2001–2008I/O and network errors
3001–3004Parsing / manifest errors
4001–4006Decoder errors
5001–5004Audio track errors
6000–6008DRM / Widevine errors
7000–7001Video frame processing errors

See the Android Errors Guide for the full description of each code.


Common Error Scenarios

1. Invalid or Expired OTP

Platforms: iOS and Android

iOS signal: message contains a license server response or "init_error_video_data"

Android signal: code 9311 (invalid) or 9312 (expired)

Cause: OTPs are short-lived. An expired or incorrect token causes DRM authentication to fail immediately.

Resolution: Generate a fresh OTP from the InkryptVideos dashboard immediately before passing it to InkPlayerParams. Do not cache OTPs.


2. DRM License Failure

Platforms: iOS (FairPlay) and Android (Widevine)

iOS signal: message starting with "Failed to get CKC: ..."

Android signal: code in the 6000–6008 range (see Android Errors Guide for specifics)

Common causes:

  • Testing on the iOS Simulator — FairPlay DRM is not supported in the Simulator
  • Network failure prevented the license server request from completing
  • OTP is invalid or expired

Resolution: Always test on a physical device. Verify network connectivity and OTP freshness.


3. Video Metadata Failure

Platforms: iOS and Android

iOS signal: message "init_error_video_data" or "init_error_fps_ce"

Android signal: code 30 or 9101

Cause: The SDK could not reach the Inkrypt API. Usually a network issue or an incorrect Video ID.

Resolution: Verify the Video ID is correct. Most cases resolve with a network reconnection and retry.


4. Network Error During Playback

Platforms: iOS and Android

iOS signal: An AVPlayer OS-level error string

Android signal: code 2001 (network connection failed) or 2002 (timeout)

Cause: Network connection dropped or CDN transient failure.

Resolution: Retry with the same params. Most transient network errors resolve on retry.


5. Developer Mode Blocked (Android Only)

Platform: Android only

Signal: code 9201 or 9202

Cause: The device has Developer Options or USB Debugging enabled. The SDK blocks playback by default to prevent unauthorized access.

Resolution: During development, pass tolerateDeveloperMode: true in InkPlayerParams. Remove or set to false for production builds.


Built-In Error UI

When an error occurs, the native player displays a built-in error screen that:

  • Shows a descriptive message to the user
  • Offers a Retry button that reloads the player with the last-used params
  • Hides playback controls while visible

No additional Flutter UI code is needed for basic error handling.