Error Handling

When something goes wrong, the SDK displays an error overlay on the player surface. This page lists every error code your users or your integration code may encounter, explains the cause, and describes what, if anything, you need to do.

Error codes fall into two groups:

  • Inkrypt errors: specific to SDK authentication, configuration, security, and session management.
  • Media errors (1000–7001+): originate from the underlying ExoPlayer/Media3 engine and reflect device or network conditions.

Inkrypt Errors

Integration / Configuration

These errors fire before playback begins and indicate a problem in how the SDK was called.

CodeNameCauseWhat to do
100Missing OTPsetOtp() was not called on InkInitParams.Builder before setParams().Ensure every setParams() call includes a non-null OTP.
200Missing Video IDsetVideoId() was not called on InkInitParams.Builder before setParams().Ensure every setParams() call includes a non-null video ID.

Network

CodeNameCauseWhat to do
20Network ErrorA network failure prevented a request from completing (no connectivity, unreachable host, or closed connection).Check device connectivity. If intermittent, the SDK retries automatically.
21SSL ErrorAn SSL/TLS handshake error occurred during a network request.Verify the device's system time is correct and that no network proxy is intercepting TLS.
30Resource Not FoundThe server returned an unexpected empty or null response for the video.Verify the video ID is correct and the video exists in your Inkrypt account.

Authentication & Authorization

CodeNameCauseWhat to do
9101API ErrorThe server returned an HTTP 400 response (e.g. account deactivated or malformed request).Check your Inkrypt Dashboard for account status.
9102UnauthenticatedThe video ID or OTP is invalid (HTTP 401).Double-check the videoId and otp values passed to setParams().
9104Access ForbiddenThe server returned HTTP 403 on the request, the OTP may not be authorized for this video or has been revoked.Re-generate a fresh OTP from your backend.
9311Invalid OTPThe OTP was rejected by the server.Verify the OTP generation logic and that the correct videoId is paired with the OTP.
9312Expired OTPThe OTP has expired (HTTP 403 on video metadata fetch).Re-generate a fresh OTP. OTPs are time-limited; generate them close to the point of playback.

Server Errors

CodeNameCauseWhat to do
9310Server Error 500The Inkrypt server returned an HTTP 500.Transient issue, retry. If persistent, contact Inkrypt support.
9320Other Server ErrorAn unclassified HTTP error from the video-info endpoint.Check the error message for details. Retry or contact support.

Session & Security

CodeNameCauseWhat to do
9201Developer Mode EnabledThe device has Developer Options turned on. The SDK blocks playback when this is detected.Nothing, A dialog is displayed to the user instruction him to disable Developer Mode. Use setTolerateDeveloperMode(true) to bypass this check.
9202USB Debugging EnabledADB / USB Debugging is enabled on the device. The SDK blocks playback.Nothing, A dialog is displayed to the user instruction him to disable USB Debugging. Use setTolerateDeveloperMode(true) during development.
9301Session Forced ExpirationThe server forcibly ended the playback session, e.g. the OTP was revoked or the user's account was deactivated while the video was playing.The error overlay is shown automatically. No action required in your app; the user will need to re-authenticate.

Installation & Version

CodeNameCauseWhat to do
3201Unsupported InstallationThe app was not installed from the Google Play Store (or another authorized distribution channel).The error overlay is shown automatically instructing the user to download the app from an official source.
21201Update RequiredThe SDK version in the installed app is out of date and the server has rejected it.The SDK shows an in-player update prompt with a link to the Play Store. No action required in your code.

Media Errors (ExoPlayer / Media3)

These error codes originate from the underlying ExoPlayerPlaybackException engine. The SDK displays a localized message for the most common ones; the rest show a generic error.

General

CodeDescription
1000Unspecified error, cause could not be identified.
1001Remote player error in a process other than the current one.
1002Live playback position fell behind the sliding window of available content.
1003Generic timeout.
1004Failed runtime check, invalid argument or illegal player state. The SDK attempts an automatic L3 DRM fallback before surfacing this.

I/O

CodeDescription
2000Unspecified I/O error.
2001Network connection failed (no connectivity, unreachable host, or closed connection).
2002Network timeout, the server took too long to respond.
2003Invalid HTTP Content-Type header from the media server.
2004Unexpected HTTP status code from the media server.
2005Media file not found.
2006Missing INTERNET permission.
2007Cleartext HTTP traffic blocked by the app's Network Security Configuration.
2008Read position is outside the valid data range.

Parsing

CodeDescription
3000Malformed media container, manifest, or unsupported format.

Decoder

CodeDescription
4001Decoder initialization failed. The SDK attempts an automatic L3 DRM fallback before surfacing this.
4002Decoder query failed.
4003Failure while decoding media samples. The SDK attempts an automatic L3 DRM fallback before surfacing this.
4004Media content exceeds the device's decoder capabilities.
4005Unsupported decoding format.
4006Decoder resources were reclaimed by a higher-priority task (e.g. a phone call).

Audio

CodeDescription
5001AudioTrack initialization failed.
5002AudioTrack write operation failed.
5003AudioTrack write operation failed in offload mode.
5004AudioTrack initialization failed in offload mode.

DRM / Widevine

CodeDescription
6001DRM protection scheme not supported by the device.
6002Device DRM provisioning failed.
6003Incompatible DRM-protected content.
6004DRM license acquisition failed. The SDK retries automatically before surfacing this.
6005Operation disallowed by the DRM license policy.
6006DRM system error. The SDK attempts an automatic L3 fallback before surfacing this.
6007DRM privileges revoked on this device.
6008DRM license has expired.

Video Frame Processing

CodeDescription
7000VideoFrameProcessor initialization failed.
7001Failure during video frame processing.

Automatic DRM Recovery

The SDK includes built-in resilience for certain DRM and decoder errors. When errors 6006, 4001, 4003, or 1004 occur, the SDK automatically retries playback using Widevine L3 (software DRM) before showing an error to the user. After 10 cumulative such failures on a device, L3 mode is persisted — subsequent sessions on that device will start in L3 directly.

The user only sees an error if the automatic recovery also fails.