This guide covers all error scenarios in the InkryptVideos SDK, how to detect them, and recommended recovery strategies.
Overview
Errors in the SDK fall into three categories:
| Category | When It Occurs | Primary Detection Point |
|---|---|---|
| Initialization errors | Before playback begins — invalid OTP, network failure during setup, FairPlay license rejection | onError callback |
| Playback errors | During active playback — network drop, CDN failure, stream corruption | onError callback |
| User-triggered retries | User taps "Retry" on the built-in error screen | onReloadPressed callback |
Receiving Errors
via InkryptVideoPlayerView Callbacks
InkryptVideoPlayerView CallbacksThis is the recommended approach for most apps. Both callbacks are optional, implement only the ones you need.
InkryptVideoPlayerView(
params: params,
onReloadPressed: { errorCode, errorMessage in
// Called when the user taps "Retry" on the error screen.
//
// Decision point: return nil to retry with the same params,
// or return a new InkPlayerParams to reload with a different video/OTP.
return nil
},
onError: { errorCode, errorMessage in
// Called whenever an error occurs — use this for logging or monitoring.
// errorMessage is the primary signal; errorCode may be nil (see Error Codes below).
print("Playback error: \(errorMessage ?? "unknown")")
MyAnalytics.shared.logEvent("player_error", properties: [
"code": errorCode as Any,
"message": errorMessage as Any
])
}
)
Error Codes
Both onError and onInkPlayerInitError receive an errorCode: Int? parameter. Understanding where this value comes from is important for building correct error handling.
errorCode is nil for almost all errors. The SDK passes nil as the error code for every internal failure: invalid configuration, missing FairPlay certificate, failed network requests, AVPlayer failures, and stream errors all produce a nil error code.
The only case where errorCode is non-nil is when the FairPlay license server returns an error response that includes a numeric "code" field in its JSON body. In that case, the SDK forwards that server-defined integer directly. The specific values are defined by the InkryptVideos license server, refer to the InkryptVideos dashboard documentation for the list of server error codes.
Use errorMessage as your primary signal, not errorCode.
Error Messages
The errorMessage: String? parameter is a more reliable signal than errorCode. The table below lists all message strings produced by the SDK itself:
| Message | What It Means |
|---|---|
"init_error_fps_ce" | Failed to fetch the FairPlay certificate from the server - 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" | Video metadata was retrieved but no valid stream URL could be constructed |
"One-Time-Password has not been set" | OTP is missing from the player configuration |
"FairPlay Certificate has not been setup for this Media Player" | Certificate was not fetched before playback was attempted |
"Please specify an URL for the Video Playback" | No playback URL is available |
"Failed to get CKC: ..." | FairPlay license exchange failed; the suffix contains the underlying error |
| AVPlayer error string | A native AVPlayer failure; the message is AVPlayerItem.error?.localizedDescription |
| License server message | A string returned directly from the InkryptVideos license server in its error response |
Common Error Scenarios
1. Invalid or Expired OTP
Symptom: The player shows an error screen immediately - the video never begins loading.
Cause: OTPs have a limited lifetime. If the OTP passed to InkPlayerParams has expired or is invalid, the player cannot authenticate.
How to identify: errorMessage will contain a license server message or "init_error_video_data".
How to handle: Generate a new OTP from the InkryptVideos dashboard and pass it to the player:
onReloadPressed: { errorCode, errorMessage in
// Provide a freshly generated OTP from the InkryptVideos dashboard
params.update(videoId: "YOUR_VIDEO_ID", otp: "YOUR_NEW_OTP")
return nil
}
Best practice: Generate the OTP as close to playback time as possible to minimise the risk of it expiring before use.
2. FairPlay License Failure
Symptom: The loading indicator appears but playback never starts; an error is eventually shown.
Message: "Failed to get CKC: ..." or a message from the license server.
Cause: The FairPlay DRM license request failed. Common causes:
- Running on the iOS Simulator - FairPlay is hardware-bound and is not supported in the Simulator
- A network error prevented the license request from reaching the license server
- The OTP is invalid, causing the license server to reject the request
How to handle:
- Always test on a physical device
- Verify network connectivity
- Confirm the OTP was freshly generated from the InkryptVideos dashboard
3. Video Metadata Failure
Symptom: Player shows an error immediately; the loading indicator appears briefly then an error screen is shown.
Message: "init_error_video_data" or "init_error_fps_ce".
Cause: The SDK could not fetch video metadata or the FairPlay certificate from the InkryptVideos API. Usually a network connectivity issue or an incorrect Video ID.
How to handle:
onReloadPressed: { errorCode, errorMessage in
// Simple retry — resolves most transient network issues
return nil
}
onError: { errorCode, errorMessage in
if errorMessage == "init_error_video_data" {
// Log and verify the Video ID is correct
Logger.shared.log("Video metadata fetch failed — check Video ID and network")
}
}
4. Network Error During Playback
Symptom: Video plays successfully but stops mid-playback with an error.
Message: An AVPlayer error string (localised, from the OS).
Cause: The network connection dropped or the CDN had a transient issue.
How to handle:
onReloadPressed: { errorCode, errorMessage in
return nil // Retry with same params — resolves most transient errors
}
onError: { errorCode, errorMessage in
Logger.shared.log("Playback error: \(errorMessage ?? "")")
}
The Built-In Error Screen
When an error occurs, the SDK automatically shows a built-in error screen that:
- Displays a descriptive error message to the user
- Shows a Retry button that triggers the
onReloadPressedcallback - Hides the player controls while the error is visible
You do not need to build a custom error UI for most use cases.
The onReloadPressed Decision Flow
onReloadPressed Decision FlowUser taps "Retry"
│
▼
onReloadPressed called
(errorCode, errorMessage)
│
├── return InkPlayerParams(...) → Player reloads with new video/OTP
│
└── return nil → Player retries with the same params
Return new InkPlayerParams when:
- The OTP has expired, pass a freshly generated one from the InkryptVideos dashboard
- You want to load a different video as a fallback
Return nil when:
- The error was transient (network hiccup)
- You want the player to simply retry the same video and OTP