Invitebase | Errors

The SDK error surface — one error model, expressed in each platform's native idiom

Every SDK surfaces the same error model, mirroring the API error object: authentication failures, invalid referral codes, invalid requests, rate limits, and network failures. Two behaviors hold everywhere:

Situation	Behavior
Bad publishable key	Authentication error on the first network call.
Invalid/expired code passed to `applyCode`	Invalid-request error with code `invalid_referral_code`.
Rate limited	Rate-limit error; batched `track` calls back off and retry automatically.
Network failure during `track`	Events are retained and retried with the same idempotency key — no data loss, no duplicates.

track never throws on any platform — events are retained offline and retried with the same idempotency key.

Every rejected promise throws InvitebaseError:

class InvitebaseError extends Error {
  type: 'invalid_request_error' | 'authentication_error' | 'rate_limit_error' | 'api_error';
  code?: string;    // machine-readable, e.g. 'invalid_referral_code'
  param?: string;   // the offending parameter, when applicable
  message: string;
}

import invitebase, { InvitebaseError } from '@invitebase/js';

try {
  await invitebase.getReferralLink('7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15');
} catch (err) {
  if (err instanceof InvitebaseError && err.type === 'authentication_error') {
    console.error('Check NEXT_PUBLIC_INVITEBASE_PUBLISHABLE_KEY');
  } else {
    throw err;
  }
}

Throwing methods throw InvitebaseError:

public enum InvitebaseError: Error {
    case authentication(message: String)       // bad publishable key
    case invalidReferralCode                    // applyCode with an invalid/expired code
    case invalidRequest(code: String?, message: String, param: String?)
    case rateLimited
    case network(underlying: Error)
}

Suspend functions throw InvitebaseException:

sealed class InvitebaseException : Exception() {
    class Authentication(override val message: String) : InvitebaseException()
    object InvalidReferralCode : InvitebaseException()
    class InvalidRequest(val code: String?, override val message: String, val param: String?) : InvitebaseException()
    object RateLimited : InvitebaseException()
    class Network(override val cause: Throwable) : InvitebaseException()
}

Promise-returning methods reject with InvitebaseError — the same shape as the Web SDK (type, code, param, message).

Hooks surface the last error in their error field instead of throwing:

const { link, error } = useReferralLink('7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15');
if (error) {
  // render a retry affordance; the hook refetches on refresh()
}

Future-returning methods throw InvitebaseException:

sealed class InvitebaseException implements Exception {
  String get message;
}

class AuthenticationException extends InvitebaseException {}   // bad publishable key
class InvalidReferralCodeException extends InvitebaseException {}
class InvalidRequestException extends InvitebaseException {
  final String? code;
  final String? param;
}
class RateLimitedException extends InvitebaseException {}
class NetworkException extends InvitebaseException {}