Error Handling#

Pulsora is resilient by default, but you should still surface errors in your application and monitoring. This guide covers client-side, server-side, and API failure modes.

Browser SDK (@pulsora/core)#

• Automatic retries — The transport queues events and retries with exponential backoff (up to maxRetries, default 10).
• Beacon fallback — Pageviews/events are sent using navigator.sendBeacon when available; otherwise Pulsora falls back to fetch.
• Queue persistence — Events stay in memory until they succeed or max retries is reached.
• Debug logs — Enable debug: true to print retry attempts and dropped events.

Handling Initialization Failures#

If pulsora.init() throws (e.g., missing window), catch it and provide a graceful fallback:

try {
  pulsora.init({ apiToken: 'pub_123' });
} catch (error) {
  console.warn('Pulsora failed to initialize', error);
}

Monitoring Dropped Events#

When debug mode is on, Pulsora logs [Pulsora] Dropped after N attempts. Use this during staging to verify connectivity (e.g., CSP misconfigurations).

React Hooks (@pulsora/react)#

• The provider exposes error via context if initialization fails.
• useEvent and usePageview return promises—await them if you need to catch errors or prevent navigation until tracking completes.

const trackEvent = useEvent();

try {
  await trackEvent('signup_submit', formData);
} catch (error) {
  logger.warn('Analytics event failed', error);
}

Revenue SDK (@pulsora/revenue)#

• Validation — Throws descriptive errors for missing fingerprint/session/customer/amount values.
• Network retries — Retries on network errors and 5xx responses up to maxRetries (default 3) with exponential backoff.
• Rate limiting — Honors Retry-After headers when the API returns 429.
• Idempotency — Use the same transaction_id to avoid duplicates when retrying manually.

Always wrap track():

try {
  await revenue.track(payload);
} catch (error) {
  logger.error('Failed to send revenue event', { error, payload });
  await queue.add('retry-revenue', payload); // optional requeue
}

REST API Errors#

The browser SDK reports these in debug logs; the revenue SDK throws.

Observability Checklist#

• ✅ Log errors from revenue.track() to your monitoring platform.
• ✅ Capture page load errors (CSP, ad blockers) by testing with debug: true.
• ✅ Fail gracefully—never block user flows if analytics fails.
• ✅ Alert on repeated 429 responses (may indicate token abuse or high volume).

Common Issues#

• CORS errors — Ensure https://pulsora.co is allowed in your CSP and reverse proxies.
• Ad blockers — Pulsora uses a neutral domain (pulsora.co) but some blockers may still intervene. Use retries and server-side tracking for critical events.
• Network offline — Events queue until the browser regains connectivity, thanks to the retry system.

Need to dig deeper? Review the API error codes →