> ## Documentation Index
> Fetch the complete documentation index at: https://developer.cashbackhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Cashback Hive SDK error reference: the errors the SDK throws and rejects with, including SdkApiError status codes, and how to handle each one.

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`.

**name** `"SdkApiError"`

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

**status** `number`

The HTTP status code.

**path** `string`

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

**message** `string`

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

```ts theme={null}
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](https://developer.cashbackhive.com/concepts/keys-and-origins.md). |
| `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 `Error`s. 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`](https://developer.cashbackhive.com/concepts/lifecycle). |
| `[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. |

## Sign-in errors

`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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.