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:
| Category | When It Occurs |
|---|---|
| Initialization errors | Before playback begins, invalid OTP, network failure, DRM license rejection |
| Playback errors | During 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
| Property | Type | Description |
|---|---|---|
code | int? | Numeric error code from the DRM license server. null for nearly all errors |
message | String? | Error message string — the primary signal for identifying the error type |
Understanding code
codecode 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
message | Meaning |
|---|---|
"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 string | Native AVPlayerItem failure — OS-level error description |
| License server string | Message 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
code | Name | Meaning |
|---|---|---|
20 | Network Error | No connectivity or request failed |
21 | SSL Error | SSL/TLS failure during a network request |
30 | Resource Not Found | Requested resource not found on server |
9101 | API Error | Server returned an error response |
9102 | Unauthenticated | Video ID or OTP is incorrect |
9104 | Missing OTP | OTP was not provided |
9201 | Developer Mode Enabled | Device has Developer Options on — use tolerateDeveloperMode: true to bypass during development |
9202 | USB Debugging Enabled | ADB debugging is on — same resolution as 9201 |
9301 | Session Forced Expiration | Server forcibly ended the session (OTP revoked or account deactivated) |
9311 | Invalid OTP | OTP rejected by the server (HTTP 401) |
9312 | Expired OTP | OTP has expired (HTTP 403) — regenerate a fresh OTP |
Media Error Codes Quick Reference
code range | Category |
|---|---|
1000–1004 | General player errors |
2001–2008 | I/O and network errors |
3001–3004 | Parsing / manifest errors |
4001–4006 | Decoder errors |
5001–5004 | Audio track errors |
6000–6008 | DRM / Widevine errors |
7000–7001 | Video 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.