Errors

useTaxKit() exposes an errors array — an unbroken stream of TaxKitError enum values reported by the iframe. The array may contain multiple errors at once (e.g. a connection sync error alongside a missing-connections warning), and may be empty.

import { useTaxKit, TaxKitError } from '@cointracker/tax-kit';

At a glance

Error	Severity	Recoverable?	Typical user-facing surface
GenericError	High	Often (transient)	Generic "something went wrong" + retry.
AuthenticationError	Fatal	After re-auth	Sign-in prompt; reload kit after.
EmbeddedHealthCheckError	Fatal	After CT recovery	Outage banner; link to status page.
MissingConnections	Info	Yes (user action)	None — iframe surfaces the prompt.
ConnectionSyncErrors	Medium	Yes (user reconnects)	Badge on tax-center entry.
TransactionsNeedsReview	Medium	Yes (user reviews)	Badge on tax-center entry.
PartnerImportError	Medium	Often (transient)	None — iframe surfaces retry.

"Recoverable" here means the user (or the iframe itself, on retry) can resolve the error without out-of-band action. Fatal errors require something outside the kit — a re-authentication, a CoinTracker incident resolution.

Error values

GenericError'generic_error'

Unexpected error. Usually transient — surface a generic "something went wrong" message and offer a retry. If it persists, contact your CoinTracker integration owner with the reproduction steps.

AuthenticationError'authentication_error'

The iframe couldn't authenticate to CoinTracker — usually because fetchAccessToken returned null, threw, or returned an expired token that couldn't be refreshed. Surface a sign-in prompt or reload the kit.

EmbeddedHealthCheckError'embedded_health_check_error'

The iframe couldn't reach CoinTracker's health endpoint on startup. Usually a network issue or a CoinTracker incident. Check status.cointracker.io if it persists.

MissingConnections'missing_connections'

The user has no connected wallets or exchanges. The iframe surfaces a connection prompt on its own — this error is mostly useful for partner-side analytics.

ConnectionSyncErrors'connection_sync_errors'

One or more of the user's connections have sync errors. The iframe surfaces a per-connection reconnect path. Use this signal to badge your tax-center entry point.

TransactionsNeedsReview'transactions_needs_review'

The user has transactions that require manual review (e.g. unrecognized swaps). The iframe surfaces a review queue. Use this signal to nudge users from your home screen.

PartnerImportError'partner_import_error'

The partner-side import step failed. Usually transient — the iframe surfaces a retry path on its own.

Pattern: switch on the error

import { useTaxKit, TaxKitError } from '@cointracker/tax-kit';

function TaxKitErrorBanner() {
  const { errors } = useTaxKit();

  if (errors.length === 0) return null;

  // Pick the highest-priority error to display.
  if (errors.includes(TaxKitError.AuthenticationError)) {
    return <Alert variant="error">Please sign in again.</Alert>;
  }
  if (errors.includes(TaxKitError.ConnectionSyncErrors)) {
    return <Alert variant="warning">Some connections need to be re-authenticated.</Alert>;
  }
  if (errors.includes(TaxKitError.TransactionsNeedsReview)) {
    return <Alert variant="info">You have transactions to review.</Alert>;
  }
  return <Alert variant="error">Something went wrong with the Tax Kit.</Alert>;
}

Errors as analytics signals

Most error values double as useful partner-side signals — they tell you when to surface a notification on a higher level than the kit itself (e.g. badging the "Tax" entry in your main nav when ConnectionSyncErrors is present). Don't suppress them — forward them to your analytics layer.

useEffect(() => {
  errors.forEach((err) => analytics.track('tax_kit_error', { code: err }));
}, [errors]);