Error Handling

Error Handling | Engagement Tools | API Hub

Widget error handling allows you to gracefully manage situations where widgets encounter problems during loading or runtime. With proper error handling, you can:

Prevent poor user experience - Hide or replace widgets that fail to load instead of showing error messages
Maintain page integrity - Keep your page layout clean even when widgets encounter issues
Provide fallback content - Display alternative content when widgets are unavailable
Debug integration issues - Identify and resolve configuration problems during development

The error handling system provides multiple approaches: silent mode for production environments, the onTrack callback for custom error handling logic, and visual error indicators for development and debugging.

#Audience

This tutorial is for developers and integrators who are implementing Sportradar widgets and need to handle potential widget errors effectively. Understanding error handling is essential for creating production-ready integrations that gracefully handle failures.

#Goals

In this tutorial you will learn:

the different types of widget errors and what causes them
how to use the silent property to suppress error messages in production
how to implement custom error handling with the onTrack callback
how to conditionally display widgets based on their loading status
how to debug widget errors during development

#Prerequisites

In order to complete this tutorial you will need:

a website with at least one Sportradar widget integrated
- if you need to integrate a widget first, see the getting started guide
basic knowledge of JavaScript and HTML
access to browser developer tools (Chrome DevTools or Firefox Developer Tools)
a text editor of your choice

Before implementing error handling, it's important to understand the types of errors that can occur and what causes them.

#Common Error Types

Sportradar widgets can encounter several types of errors, each with different causes and solutions:

#Configuration Errors

These errors occur when a widget is missing required parameters or has invalid configuration:

No widget displayed - The widget container remains empty
"Something went wrong..." message - Invalid or missing matchId, seasonId, tournamentId, or other required parameters
Unrecognized widget - The widget name is incorrect or not supported

Common causes:

Missing or incorrect widget initialization script
Wrong Client ID in the widgetloader URL
Incorrect widget element selector
Invalid widget name

#Data Availability Errors

These errors occur when valid configuration exists but data is not available:

"No statistics available" - The match has not started yet or statistics are not yet available
"No data available" - Requested data does not exist for the given parameters

Common causes:

Match has not started
Data is temporarily unavailable from the data provider
Requested resource does not exist

#Licensing Errors

These errors occur when there are issues with widget licensing:

"No license" error icon - Your account does not have a valid license for the requested widget or data

Common causes:

Missing or expired license
Attempting to access data outside your license scope

For detailed information about licensing errors and how to resolve them, see the Licensing page.

#General Errors

Unexpected errors that don't fall into the above categories:

Generic error icon - System or network errors

If you encounter this type of error, contact support with details about your configuration and any error messages in the browser console.

#Error Handling Approaches

There are two main approaches to handling widget errors: using the silent property for simple error suppression, or implementing custom logic with the onTrack callback for more sophisticated error handling.

#Approach 1: Silent Mode (Production)

The silent property is the simplest way to prevent error messages from being displayed to end users. When set to true, the widget will not render error icons or messages, keeping your page clean even when errors occur.

Example:

SIR('addWidget', '#widget-container', 'match.lmtPlus', {
    matchId: 12345678,
    silent: true  // Suppress error display
});

When to use silent mode:

Production environments where you want to hide errors from users
When you have alternative content or fallback mechanisms in place
For optional widgets that enhance the page but aren't critical

Limitations:

Errors are suppressed but not handled - the widget simply won't display
You cannot execute custom logic based on error states
The container element may remain empty, potentially affecting page layout

#Approach 2: Custom Error Handling With onTrack

The onTrack callback provides fine-grained control over widget behavior by allowing you to execute custom code when specific events occur, including errors. This approach enables conditional display, fallback content, and advanced error recovery strategies.

The onTrack function receives two parameters:

Parameter	Type	Description
`eventType`	`string`	The type of event that occurred: `'data_change'`, `'odds_click'`, `'social_share'`, or `'license_error'`
`data`	`object`	Event-specific data, including an `error` property when errors occur

When to use onTrack:

When you need to show/hide UI elements based on widget status
To implement fallback content when widgets fail to load
To track and log errors for monitoring purposes
For conditional widget display (e.g., tabs that should only appear if the widget loads)

For detailed information about onTrack events and parameters, see the onTrack documentation.

Let's implement a complete solution that loads a widget conditionally and only displays a toggle button if the widget loads successfully without errors.

When developing and testing your widget integration, debugging errors effectively is crucial for identifying and resolving issues quickly.

#Enable Error Display During Development

Always set silent: false (or omit the silent property, as this is the default) during development. This ensures error messages and icons are displayed, making it easier to identify problems.

SIR('addWidget', '#widget-container', 'match.scoreboard', {
    matchId: 12345678,
    silent: false  // Show errors during development
});

#Use Browser Developer Tools

Browser developer tools are essential for debugging widget errors:

Open the Console
- Chrome: Press F12 or Ctrl+Shift+J (Windows/Linux) / Cmd+Option+J (Mac)
- Firefox: Press F12 or Ctrl+Shift+K (Windows/Linux) / Cmd+Option+K (Mac)
Look for Error Messages
- Widget errors often include descriptive messages in the console
- Check for network errors that might indicate connectivity issues
- Review any stack traces to identify where errors occur
Inspect Network Requests
- Open the Network tab in developer tools
- Look for failed requests (marked in red)
- Check if the widgetloader script loaded successfully
- Verify that data requests to Sportradar APIs complete successfully

#Common Debugging Steps

#Log Error Information

Implement comprehensive error logging to help diagnose issues:

const onTrack = (eventType, data) => {
    console.log('Widget event:', eventType);
    
    if (eventType === 'data_change') {
        if (data.error) {
            // Log detailed error information
            console.error('Widget error occurred:',

#Best Practices

Follow these best practices to implement robust error handling:

#1. Different Configurations for Development and Production

Use environment-specific settings to balance debugging capabilities with user experience:

const isProduction = window.location.hostname !== 'localhost';

SIR('addWidget', '#widget-container', 'match.scoreboard', {
    matchId: 12345678,
    silent: isProduction,  // Hide errors in production only
    onTrack: (eventType, data) => {

#2. Provide Fallback Content

Always consider what users should see when a widget fails to load:

html

<div id="widget-wrapper">
    <div id="widget-container"></div>
    <div id="fallback-content" style="display: none;">
        <p>Live match data is temporarily unavailable.</p>
        <a href="/schedule">View match schedule</

#3. Handle Licensing Errors Gracefully

Licensing errors require special attention as they indicate configuration or subscription issues:

SIR('addWidget', '#widget-container', 'match.scoreboard', {
    matchId: 12345678,
    onTrack: (eventType, data) => {
        if (eventType === 'license_error') {
            console.error('License error:', data.error);
            // Notify your team about license issues

#4. Validate Configuration Before Loading

Prevent errors by validating configuration before attempting to load widgets:

function loadWidget(matchId) {
    // Validate matchId
    if (!matchId || typeof matchId !== 'number') {
        console.error('Invalid matchId:', matchId);
        return;
    }
    
    SIR('addWidget', '#widget-container', 'match.scoreboard'

#5. Clean up on Errors

Remove or hide widget containers when errors occur to maintain clean page layouts:

SIR('addWidget', '#widget-container', 'match.scoreboard', {
    matchId: 12345678,
    onTrack: (eventType, data) => {
        if (eventType === 'data_change' && data.error) {
            const container = document.getElementById('widget-container')

#Further Reading

onTrack Documentation - Detailed information about the onTrack callback and all available events
Widget Errors Reference - Comprehensive list of widget error types and solutions
Troubleshooting Guide - Common widget integration issues and how to resolve them
Getting Started Guide - Basic widget integration steps
Licensing Documentation - Information about widget licensing and related errors
SIR API Reference - Complete API documentation for the SIR global function
Support - How to get help with widget integration issues

html

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Widget Error Handling Demo</title>
    <style>
        #page-content {
            display: flex;
            align-items: center;
            justify-content: center;
            flex-direction: column;
        }
    </style>
</head>
<body>
    <!-- Main page content area -->
    <div id="page-content">
        <button id="toggle-button" style="display: none">
            Toggle Widget Display
        </button>
    </div>
    
    <!-- Hidden loading area for widget -->
    <div id="loading-area" style="display: none">
        <div id="widget-container" class="sr-widget"></div>
    </div>
    
    <script>
        // Get DOM elements
        const loadingArea = document.getElementById('loading-area');
        const pageContent = document.getElementById('page-content');
        const widget = document.getElementById('widget-container');
        const toggleButton = document.getElementById('toggle-button');
        
        // Initialize widgets framework
        (function(a,b,c,d,e,f,g,h,i){a[e]||(i=a[e]=function(){
            (a[e].q=a[e].q||[]).push(arguments)},i.l=1*new Date,i.o=f,
            g=b.createElement(c),h=b.getElementsByTagName(c)[0],
            g.async=1,g.src=d,g.setAttribute("n",e),
            h.parentNode.insertBefore(g,h)
        )})(window,document,"script",
            "https://widgets.sir.sportradar.com/sportradar/widgetloader",
            "SIR", {
                language: "en",
                theme: false
            }
        );
        
        // Error handling callback
        const onTrack = (eventType, data) => {
            if (eventType === 'data_change') {
                if (!data.error) {
                    // Widget loaded successfully
                    loadingArea.removeChild(widget);
                    pageContent.appendChild(widget);
                    toggleButton.style.display = 'block';
                } else {
                    // Widget encountered an error
                    console.error('Widget error:', data.error);
                }
            }
        };
        
        // Toggle widget visibility
        const toggleWidget = () => {
            const isHidden = widget.style.display === 'none';
            widget.style.display = isHidden ? 'block' : 'none';
        };
        toggleButton.onclick = toggleWidget;
        
        // Load widget with error handling
        SIR("addWidget", "#widget-container", "match.scoreboard", {
            matchId: 43406689,
            onTrack: onTrack
        });
    </script>
</body>
</html>

Error Handling

#What Is Widget Error Handling?

#Audience

#Goals

#Prerequisites

#Understanding Widget Errors

#Common Error Types

#Configuration Errors

#Data Availability Errors

#Licensing Errors

#General Errors

#Error Handling Approaches

#Approach 1: Silent Mode (Production)

#Approach 2: Custom Error Handling With onTrack

#Interactive Code Tutorial: Conditional Widget Display

#Debugging Widget Errors

#Enable Error Display During Development

#Use Browser Developer Tools

#Common Debugging Steps

#Log Error Information

#Best Practices

#1. Different Configurations for Development and Production

#2. Provide Fallback Content

#3. Handle Licensing Errors Gracefully

#4. Validate Configuration Before Loading

#5. Clean up on Errors

#Further Reading

Step 1: Set up HTML Structure

Step 2: Create Widget Container and Controls

Step 3: Get DOM References

Step 4: Initialize Widget Framework

Step 5: Implement Error Handling Callback

Step 6: Add Toggle Functionality

Step 7: Load the Widget

Error Handling

Error Handling

#What Is Widget Error Handling?

#Audience

#Goals

#Prerequisites

#Understanding Widget Errors

#Common Error Types

#Configuration Errors

#Data Availability Errors

#Licensing Errors

#General Errors

#Error Handling Approaches

#Approach 1: Silent Mode (Production)

#Approach 2: Custom Error Handling With onTrack

Expanded Table

#Interactive Code Tutorial: Conditional Widget Display

#Debugging Widget Errors

#Enable Error Display During Development

#Use Browser Developer Tools

#Common Debugging Steps

#Log Error Information

#Best Practices

#1. Different Configurations for Development and Production

#2. Provide Fallback Content

#3. Handle Licensing Errors Gracefully

#4. Validate Configuration Before Loading

#5. Clean up on Errors

#Further Reading

Step 1: Set up HTML Structure

Step 2: Create Widget Container and Controls

Step 3: Get DOM References

Step 4: Initialize Widget Framework

Step 5: Implement Error Handling Callback

Step 6: Add Toggle Functionality

Step 7: Load the Widget