Errors and retries

Both SDKs queue events and resend a failed request on their own. A failed send does not stop the page. This page lists what the SDK does without code, what a call returns to the caller, and what to do for each error.

What the SDK does on its own

Failure	What Analytics Web does
Network error, timeout, or lost connection	Waits `retryDelay` milliseconds, then resends. Each attempt doubles the delay. Stops after `retryAttempts` retries.
HTTP `5xx`	Resends with the same backoff.
HTTP `429`	Waits, then resends with the same backoff.
HTTP `4xx` other than `429`	Logs the error in debug mode and drops the batch. No retry.
Invalid event data	Logs a warning and continues.
Browser offline	Keeps events in the queue. Sends them when the browser is online.
Page unload	Sends the queue with the Beacon API.

Grain Tag has the same queue. It resends a failed request up to retryAttempts times and sends the queue with the Beacon API on page unload. Read Configuration options for retryAttempts and retryDelay in both SDKs. With the defaults, Analytics Web waits 1 second, then 2 seconds, then 4 seconds between four attempts in total.

Limit	Value	Where
Attempts per request	`retryAttempts` + 1, `4` by default	Analytics Web `sendEvents`
First delay	`retryDelay`, `1000` ms by default	Analytics Web
Delay growth	doubles after each attempt	Analytics Web

What the caller sees

Call	SDK	Returns	On failure
`track(eventName, properties?)`	Grain Tag	`void`	Nothing reaches the caller.
`track(eventName, properties?, options?)`	Analytics Web	`Promise<void>`	The promise settles after the event is queued, or after the send when `options.flush` is `true`.
`trackLogin`, `trackPurchase`, and the other template methods	Analytics Web	`Promise<void>`	Same as `track`.
`setProperty(properties, options?)`	Analytics Web	`Promise<void>`	Can reject. Catch the promise.
`getConfig(key)`	Analytics Web	`string \| undefined`	Returns the cached value, then the default from `defaultConfigurations`. Never throws.
`getConfigAsync(key, options?)`	Analytics Web	`Promise<string \| undefined>`	Rejects when the fetch fails. Catch it and call `getConfig`.
`fetchConfig(options?)`	Analytics Web	`Promise<RemoteConfigResponse \| null>`	Resolves to `null` when the fetch fails.
`useConfig(key)`	React	`{ value, isRefreshing, error, refresh }`	`error` holds an `Error`. `value` keeps the cached or default value.
`authProvider.getToken()`	Analytics Web	`Promise<string> \| string`	An error thrown here reaches the SDK. Catch it inside `getToken`.

track in Analytics Web queues the event and returns. Do not wait for it before you show the page.

grain.track('button_clicked', { button: 'signup' });
renderPage();

For an event that must not be lost, pass flush: true and catch the result.

try {
  await grain.trackPurchase({ orderId: order.id, total: order.total }, { flush: true });
} catch (error) {
  console.error('Purchase event failed', error);
}

Configuration reads never break the page. getConfig returns the cache or the default.

let heroText: string | undefined;

try {
  heroText = await grain.getConfigAsync('hero_text', { forceRefresh: true });
} catch (error) {
  heroText = grain.getConfig('hero_text');
}

Read Remote configuration for the cache order.

Debug output

Analytics Web writes an error to the console only when debug is true. In production the SDK is silent.

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  debug: true
});

Each logged error has the FormattedError shape from the package types.

interface FormattedError {
  code: string;
  message: string;
  digest: ErrorDigest;
  timestamp: string;
  context: string;
  originalError?: unknown;
}

interface ErrorDigest {
  eventCount: number;
  totalProperties: number;
  totalSize: number;
  eventNames: string[];
  userIds: string[];
}

Field	Holds
`code`	A short code such as `NETWORK_ERROR`, `TIMEOUT_ERROR`, `CLIENT_ERROR`, `SERVER_ERROR`, `AUTH_ERROR`, `RATE_LIMIT_ERROR`, `PARSE_ERROR`, or `GENERAL_ERROR`.
`message`	The message of the original error.
`digest`	Counts and names of the events in the failed batch. The digest holds no property values.
`timestamp`	When the SDK logged the error, as an ISO string.
`context`	The operation that failed, for example `sendEvents (attempt 4/4)`.
`originalError`	The value that was thrown.

Grain Tag writes its activity to the console when debug is true in GrainTagConfig.

Errors

Error	Cause	What to do
`NETWORK_ERROR`, `Failed to fetch`, `Network request failed`	The browser cannot reach `clientapis.grainql.com`.	Nothing. The SDK resends. If it repeats, read Troubleshooting.
`TIMEOUT_ERROR`	The request took too long.	Nothing. The SDK resends.
`AUTH_ERROR`, `Unauthorized`, `Invalid token`	The secret key or the JWT is wrong, or the JWT expired.	Make sure that `authStrategy` matches the credential. Return a fresh token from `getToken`. Read Authentication.
`CLIENT_ERROR` with `Invalid event` or `Missing required field`	The event body is malformed.	Make sure that `eventName` is a string and that `properties` is a plain object.
`RATE_LIMIT_ERROR`, `Too many requests`	The tenant sent too many requests.	Nothing. The SDK waits and resends. Raise `batchSize` and `flushInterval` to send fewer requests.
`SERVER_ERROR`	The Grain API returned `5xx`.	Nothing. The SDK resends.
`PARSE_ERROR`	The response was not valid JSON.	Make sure that `apiUrl` points at the Grain API and not at a proxy that rewrites the body.

Rules for the caller

Do not wait for track before you show the page. Analytics runs in the background.
Set a value in defaultConfigurations for every configuration key that the page needs.
Log errors. Do not throw them at the user.
For an event that must not be lost, pass flush: true and catch the promise.
Catch errors inside authProvider.getToken() and return a fresh token from there.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

What the SDK does on its own

What the caller sees

Debug output

Errors

Rules for the caller

​What the SDK does on its own

​What the caller sees

​Debug output

​Errors

​Rules for the caller

What the SDK does on its own

What the caller sees

Debug output

Errors

Rules for the caller