Fatal versus non-fatal errors in the IMA SDKs

We’ve seen an increase in support questions recently on fatal and non-fatal errors in the IMA SDKs, so we’re here to explain when and why each is fired, and how you should handle one versus the other.

When are fatal and non-fatal errors fired?

Simply put, a fatal error is fired by the SDK when there is no chance for the SDK to play an ad for the remainder of the current video. There are two common scenarios for fatal ad errors. The first is when the SDK itself fails to load. The second (and more common) is when you are requesting one and only one ad, and that ad request fails to return a valid ad.

A non-fatal error is fired by the SDK when something goes wrong with an ad, but the SDK could potentially play other ads. The most common scenario for a non-fatal error occurs when you’re requesting a pod or playlist of ads, and one ad fails to load. Because it could still play other ads in that pod or playlist, the SDK fires a non-fatal error and moves on to attempt the next ad.

How can I tell the difference between a fatal and a non-fatal error?

Fatal errors are what we call “top-level” errors. They trigger one of the following events, depending on your particular SDK:

SDK Triggered event or delegates
HTML5 onAdError(AdErrorEvent)
Android AdErrorEvent.AdErrorListener.onAdError(AdErrorEvent)
iOS adsLoader:failedWithErrorData
Flash adsLoadErrorHandler(AdErrorEvent)

Non-fatal errors are wrapped in a LOG type AdEvent. That event is sent to your AdsManager event listener or delegate. You can access the error message from the LOG event as follows:

SDK Error Data
HTML5 AdEvent.getAdData()[‘adError’].getMessage()
Android AdEvent.getAdData()[‘errorMessage’]
iOS IMAAdEvent.adData[@”logData”]
Flash Error(Event.adData.error).message

How should I handle fatal and non-fatal errors?

When you get a fatal error, you should destroy your AdsManager and play your content video. When you get a non-fatal error, you are not obliged to do anything for video and ad playback to continue - you can log the error message using the snippets shown in the table above for informational purposes.

As always, if you have any questions, feel free to contact us via the support forum.