---
title: "Error Handling"
canonical_url: "https://apidocs.sportradar.com/resources/widgets/docs/tutorials/troubleshooting/error-handling"
markdown_url: "https://apidocs.sportradar.com/resources/widgets/docs/tutorials/troubleshooting/error-handling.md"
last_updated: "2026-03-23T13:02:40Z"
---

# Error Handling

## What Is Widget Error Handling?

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](https://apidocs.sportradar.com/resources/widgets/docs/tutorials.md)
- basic knowledge of JavaScript and HTML
- access to browser developer tools (Chrome DevTools or Firefox Developer Tools)
- a text editor of your choice

## Understanding Widget Errors

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](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/troubleshooting/licensing-errors.md) 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](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/troubleshooting/support.md) 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.

> **Tip**
>
> Use `silent: true` in production environments to ensure end users never see technical error messages. Use `silent: false` (the default) during development to help identify and fix issues.

**Example:**

```js
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](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/tracking-guide.md).

## Interactive Code Tutorial: Conditional Widget Display

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

```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>
```

1. **Step 1**

   #### Step 1: Set up HTML Structure

   Create the basic HTML structure with two key areas:

   - A visible `page-content` area for UI controls
   - A hidden `loading-area` where the widget initially loads

   The hidden loading area prevents the widget from being visible until we verify it loaded without errors.

2. **Step 2**

   #### Step 2: Create Widget Container and Controls

   Add the widget container inside the hidden loading area and a toggle button in the main content area. The button starts hidden (`display: none`) and will only be shown if the widget loads successfully.

3. **Step 3**

   #### Step 3: Get DOM References

   Store references to all DOM elements you'll need to manipulate: the loading area, page content area, widget container, and toggle button. This makes the code cleaner and more efficient.

4. **Step 4**

   #### Step 4: Initialize Widget Framework

   Initialize the Sportradar widget framework using the standard initialization snippet. This loads the widget library asynchronously and sets up the global `SIR` function.

   Replace `'sportradar'` in the URL with your actual Client ID.

5. **Step 5**

   #### Step 5: Implement Error Handling Callback

   Create the `onTrack` callback function to handle widget events. When a `data_change` event occurs, check if there's an error:

   - **No error**: Move the widget from the hidden loading area to the visible page content and show the toggle button
   - **Has error**: Log the error to the console for debugging

   This approach ensures UI elements only appear when the widget is ready and error-free.

6. **Step 6**

   #### Step 6: Add Toggle Functionality

   Implement a function to toggle widget visibility when the button is clicked. This provides user control over when the widget is displayed.

7. **Step 7**

   #### Step 7: Load the Widget

   Finally, load the widget using `SIR('addWidget')` with:

   - The widget container selector
   - The widget name (`match.scoreboard`)
   - Configuration including `matchId` and the `onTrack` callback

   The `onTrack` callback will handle the success/error logic defined in Step 5.

## Debugging Widget 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.

```js
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:

1. **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)

2. **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

3. **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

**Widget Not Appearing**

**Symptoms:** Nothing is displayed, no error message, widget container remains empty.

**Debugging steps:**

1. Verify the widgetloader script is included and loaded correctly
2. Check that your Client ID in the widgetloader URL is correct
3. Ensure the widget container element exists in your HTML
4. Confirm the widget name is spelled correctly
5. Check browser console for JavaScript errors

**Example check:**

```js
// Verify SIR function is available
console.log(typeof SIR); // should output "function"
```

**Configuration Errors**

**Symptoms:** "Something went wrong..." error message displayed.

**Debugging steps:**

1. Check browser console for specific error details
2. Verify all required parameters are provided (e.g., `matchId`, `seasonId`)
3. Confirm parameter values are valid (correct ID format and values)
4. Review the widget documentation for required properties

**Example check:**

```js
// Add onTrack to log error details
SIR('addWidget', '#widget', 'match.lmtPlus', {
    matchId: 12345678,
    onTrack: (eventType, data) => {
        if (eventType === 'data_change' && data.error) {
            console.error('Widget error details:', data);
        }
    }
});
```

**Data Availability**

**Symptoms:** "No statistics available" or "No data available" message.

**Debugging steps:**

1. Verify the match has started (if using match widgets)
2. Check that the match ID, season ID, or tournament ID is correct
3. Confirm the data is available for your license level
4. Try with a different, known-good ID to isolate the issue

**Testing approach:**

```js
// Test with a well-known match ID
SIR('addWidget', '#widget', 'match.scoreboard', {
    matchId: 43406689,  // Use a known valid match
    onTrack: (eventType, data) => {
        console.log('Event:', eventType, 'Data:', data);
    }
});
```

### Log Error Information

Implement comprehensive error logging to help diagnose issues:

```js
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:', {
                error: data.error,
                widgetData: data,
                timestamp: new Date().toISOString()
            });
        } else {
            console.log('Widget loaded successfully');
        }
    }
    
    if (eventType === 'license_error') {
        console.error('License error:', data.error);
    }
};
```

## 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:

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

SIR('addWidget', '#widget-container', 'match.scoreboard', {
    matchId: 12345678,
    silent: isProduction,  // Hide errors in production only
    onTrack: (eventType, data) => {
        if (!isProduction && data.error) {
            // Detailed logging in development
            console.error('Widget error:', data.error);
        }
        // Production error tracking (e.g., send to analytics)
        if (isProduction && data.error) {
            // trackError(data.error);
        }
    }
});
```

### 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</a>
    </div>
</div>

<script>
const showFallback = () => {
    document.getElementById('widget-container').style.display = 'none';
    document.getElementById('fallback-content').style.display = 'block';
};

SIR('addWidget', '#widget-container', 'match.scoreboard', {
    matchId: 12345678,
    silent: true,
    onTrack: (eventType, data) => {
        if (eventType === 'data_change' && data.error) {
            showFallback();
        }
    }
});
</script>
```

### 3. Handle Licensing Errors Gracefully

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

```js
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
            // notifyAdmin('Widget license error', data.error);
            
            // Show user-friendly message
            document.getElementById('widget-container').innerHTML = 
                '<p>This feature is currently unavailable.</p>';
        }
    }
});
```

### 4. Validate Configuration Before Loading

Prevent errors by validating configuration before attempting to load widgets:

```js
function loadWidget(matchId) {
    // Validate matchId
    if (!matchId || typeof matchId !== 'number') {
        console.error('Invalid matchId:', matchId);
        return;
    }
    
    SIR('addWidget', '#widget-container', 'match.scoreboard', {
        matchId: matchId,
        onTrack: (eventType, data) => {
            if (eventType === 'data_change' && data.error) {
                console.error('Widget failed to load:', data.error);
            }
        }
    });
}

// Usage
loadWidget(12345678);  // Valid
loadWidget('invalid'); // Prevented with error message
```

### 5. Clean up on Errors

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

```js
SIR('addWidget', '#widget-container', 'match.scoreboard', {
    matchId: 12345678,
    onTrack: (eventType, data) => {
        if (eventType === 'data_change' && data.error) {
            const container = document.getElementById('widget-container');
            // Option 1: Hide the container
            container.style.display = 'none';
            
            // Option 2: Remove it entirely
            // container.remove();
            
            // Option 3: Replace with message
            // container.innerHTML = '<p>Content unavailable</p>';
        }
    }
});
```

## Further Reading

- [onTrack Documentation](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/tracking-guide.md) - Detailed information about the `onTrack` callback and all available events
- [Widget Errors Reference](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/troubleshooting/widget-errors.md) - Comprehensive list of widget error types and solutions
- [Troubleshooting Guide](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/troubleshooting/troubleshooting-guide.md) - Common widget integration issues and how to resolve them
- [Getting Started Guide](https://apidocs.sportradar.com/resources/widgets/docs/tutorials.md) - Basic widget integration steps
- [Licensing Documentation](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/troubleshooting/licensing-errors.md) - Information about widget licensing and related errors
- [SIR API Reference](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/SIR.md) - Complete API documentation for the SIR global function
- [Support](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/troubleshooting/support.md) - How to get help with widget integration issues