Errors

The SDK surfaces two kinds of failure: API errors, which are promise rejections from network calls, and SDK errors, which are thrown synchronously when a method is used incorrectly.

API errors: `SdkApiError`

Any method that calls the API (offers.list, offers.get, member.get, member.activity, and auth.signIn after the popup completes) rejects with an SdkApiError when the response is not 2xx.

"SdkApiError"

Use this to identify the error type. The class isn’t exported, so check err.name rather than instanceof.

number

The HTTP status code.

string

The API path that failed, e.g. "/offers".

string

Formatted as "<status> <statusText> from <path>", e.g. "403 Forbidden from /offers".

try {
  await sdk.offers.list();
} catch (err) {
  if (err?.name === "SdkApiError") {
    switch (err.status) {
      case 401: /* bad or rotated key */ break;
      case 403: /* origin not allowed */ break;
      default:  /* server or network problem */
    }
  }
}

Status codes

Status	Meaning	Fix
`401`	The publishable key is invalid or has been rotated; or, for member endpoints, the token has expired.	Check the key. For expired tokens the SDK signs the member out automatically on load.
`403`	The current origin isn’t in the property’s allowed origins.	Add the origin in the publisher portal. See Keys and allowed origins.
`404`	Resource not found. `offers.get()` converts this to `null` instead of rejecting.	Check the slug.
`429`	Rate limited.	Back off and retry. Avoid calling `offers.list()` on every keystroke without debouncing.
`5xx`	Cashback Hive server error.	Retry with backoff. Show a non-blocking error in your UI.

A network failure (offline, DNS, blocked by CSP) rejects with the browser’s own TypeError: Failed to fetch rather than an SdkApiError.

SDK errors

Thrown synchronously as plain Errors. These indicate a bug in the integration rather than a runtime condition, so they’re best fixed in code rather than caught.

Message	Thrown by	Cause
`[CashbackHive] init requires a publishable key`	`init()`	`options.key` is missing or empty.
`[CashbackHive] call init({ key }) first, or set data-key on the script tag`	Any API or tracking method	Called before initialisation. Wait for `cbh:ready`.
`[CashbackHive] unknown offer "<slug>"; call offers.list() or offers.get() first`	`openOffer()`, `trackingUrl()`	A slug string was passed that isn’t in the offer cache. Fetch it first or pass the offer object.
`[CashbackHive] click tracking is not available for "<slug>"`	`openOffer()`, `trackingUrl()`	The offer’s `clickUrl` is `null`. Check before rendering a call to action.
`[CashbackHive] member is not signed in`	`member.activity()`	No token is stored. Check `auth.isSignedIn()` first.

auth.signIn() rejects with a plain Error:

Message	Meaning
`Sign-in window was closed`	The member closed the popup. Treat as a cancel.
`Sign-in failed`	The sign-in page reported a generic failure.
(other)	A specific message from the sign-in page.

It can also reject with an SdkApiError if the member profile fetch after sign-in fails.

Event handler errors

Exceptions thrown inside an on() handler are caught by the SDK and logged:

[CashbackHive] handler for auth:change threw Error: …

They don’t propagate and don’t stop other handlers from running.

Get started

Installation

Widgets

Guides

API reference

Resources

API errors: `SdkApiError`

Status codes

SDK errors

Event handler errors

​API errors: SdkApiError

​Status codes

​SDK errors

​Sign-in errors

​Event handler errors

API errors: `SdkApiError`

Status codes

SDK errors

Sign-in errors

Event handler errors