Handle errors with the Wowza Flowplayer Apple SDK

The Wowza Flowplayer Apple SDK provides the ability to track and handle errors, emitting them as events for delegates and through the NotificationCenter.

For a good user experience, you can listen to these error events and examine the error objects. You can then handle errors gracefully by implementing error-handling logic that makes your iOS or tvOS application more reliable and robust.

When working with this SDK, you can leverage the Ad Error, PlayerError, and Swift.Error error types.


AdError is a custom error type specific to ad-related and DAI stream-related issues in the Apple SDK. It's thrown for any issues triggered by ads, such as when ads are unavailable, ad loading fails, ads fail to display, or when there's an invalid ad request.

This table includes ad error conditions to help with troubleshooting. DAI-stream related errors for iOS and tvOS are mapped to the IMAAdError class and IMAErrorCode enumeration, but custom codes are also available.

Error condition Description
adDisplayError An error occurred during ad display.
adLoadFailed Failed to load an ad.
adSlotNotVisible The ad slot is not visible on the page.
apiError Generic invalid usage of the API.
companionAdLoadingFailed A companion ad failed to load or render.
contentPlayheadMissing Content playhead was not passed in, but a list of ads was returned from the server.
invalidAdRequest An invalid ad request occurred.
invalidArguments Invalid arguments were provided to SDK methods.
noAdAvailable No ad is available to play.
noAvPlayerInstance No AVPlayer instance is available for playback.
osRuntimeTooOld The version of the operating system runtime is too old.
playlistMalformedResponse Ads list response was malformed.
requiredListenersNotAdded Listener for at least one of the required VAST events was not added.
unknownError An unexpected error occurred and the cause is unknown.
vastAssetNotFound No assets were found in the VAST ad response.
vastEmptyResponse A VAST response containing a single tag with no child tags was returned.
vastInvalidUrl A VAST wrapper loaded and a subsequent wrapper or inline ad load resulted in a 404 response code.
vastLinearAssetMismatch Assets were found in the VAST ad response for a linear ad, but none of them matched the video player’s capabilities.
vastLoadTimeout The VAST URI provided was either unavailable or reached a timeout as defined by the video player.
vastMalformedResponse The ad response was not recognized as a valid VAST ad.
vastMediaLoadTimeout Failed to load media assets from a VAST response within the default timeout.
vastTooManyRedirects The maximum number of VAST wrapper redirects was reached.
vastTraffickingError A trafficking error occurred. The video player received an ad type that it wasn't expecting and/or it cannot display.
videoElementRequired A video element was not specified where it was required.
videoElementUsed Another VideoAdsManager is still using the video. It must be unloaded before another ad can play on the same element.
videoPlayError There was an error playing the video ad.

IMAMetadata object

The IMAMetadata struct is designed to capture information related to ad playback and errors in the context of Google's Interactive Media Ads (IMA) framework.

You can use this object with error events to understand what caused an underlying advertising error. For example, to get useful metadata about a current IMA instance, combine this object with the AdError type and pass it as an optional parameter to the player(_:didAdFailWith:for:with:) method. The Apple SDK only returns the IMAMetadata object when an error occurs with a particular ad.

To handle cases where an ad fails to load or display the ad type and IMA snapshot, see the FlowplayerAdDelegate method or the NotificationCenter.

The following table describes the properties you can use with the IMAMetadata object.

Properties Description
type The current type of metadata.
adBreakTime The current ad break time in seconds.
adRemainingSeconds The remaining ad display time in seconds.
adMuted A boolean flag indicating if the ads were muted or not.
adDurationSeconds The total duration of the ads in seconds.
adErrorReason The error reason if an ad error occurred.
adVastError The VAST (Video Ad Serving Template) error reason if applicable.
adVastErrorType The VAST error type if applicable.
adRequestLoadTime The total time required to load the ads in seconds.


PlayerError is a custom error type specific to player-related issues in the Apple SDK. It's thrown for any issues triggered by the player, such as invalid configuration, invalid access token, or general playback errors. This table includes player error conditions to help with troubleshooting.

Error condition Description
invalidConfig The player configuration is invalid.
invalidAccessToken The access token provided for authentication is invalid.
playbackError(_ error: Error) An error occurred during playback. Returns a Swift.Error as its argument.


Within the Apple SDK framework, we take advantage of the native Swift way of defining and handling errors using the Error protocol. See Swift error type for more information.