Janus Client SDK

A lightweight JavaScript library for tracking events from web applications. Automatically handles batching, retries, rate limiting, and persistence.

Lightweight (~3KB)Auto RetryBatchingPersistence

Error Handling

Error Types & Behavior#

The SDK handles errors gracefully:

Scenario	Behavior
Rate Limited (429)	Waits for server-specified reset time, then retries
Server Error (5xx)	Retries up to 3 times with exponential backoff
Network Error	Retries up to 3 times, persists queue for next session
Origin Not Allowed (403)	Logs error, events are dropped (fix your allowed origins)
Invalid Request (400)	Logs error, events are dropped

Exponential Backoff#

Retries use exponential backoff with jitter:

Retry	Delay
Retry 1	~1 second
Retry 2	~2 seconds
Retry 3	~4 seconds
Maximum delay	30 seconds

Queue Persistence#

If the user closes the page or navigates away, queued events are saved to localStorage and will be sent on the next page load.

Error Callback (onError)#

Use the onError callback to programmatically monitor SDK health. The callback receives an error type string and a details object. The SDK catches exceptions in your callback so it never impacts tracking.

Error Type	When	Detail Fields
rate_limit	Server returned 429	status, retryIn
server_error	Server returned 5xx (retrying)	status, retry, maxRetries
server_error_final	Server returned 5xx (retries exhausted)	status, eventsDropped
network_error	Fetch threw (retrying)	message, retry, maxRetries
network_error_final	Fetch threw (retries exhausted)	message, eventsPersisted
origin_blocked	Server returned 403	status, eventsDropped
bad_request	Server returned 400 or other client error	status, eventsDropped

javascript

Janus.init('jns_your_api_key', {
    onError: (type, details) => {
        console.warn('Janus error:', type, details);

        // Example: forward to your error tracker
        if (window.Sentry) {
            Sentry.captureMessage(`Janus SDK: ${type}`, {
                level: 'warning',
                extra: details
            });
        }
    }
});

Automatic Context User Journeys

Need Help?

If you have questions or run into issues, check out our troubleshooting guide or reach out to our support team.

Troubleshooting Guide