Errors

SDK calls either throw or return a failure payload, depending on the method. Start with try/catch and then inspect response details.

Catch failures

Most read operations throw Error with the GraphQL message. Handle them with try/catch and surface the message.

try {
  const orders = await heb.getOrders()
  console.log(orders.pageProps?.orders?.length)
} catch (err) {
  console.error((err as Error).message)
}

---

Handle cart responses

Cart mutations return CartResponse with success and errors. Common failures include missing store context and expired sessions.

const result = await heb.addToCart(productId, skuId, 2)

if (!result.success) {
  console.log(result.errors)
}

---

Inspect GraphQL responses

Low-level helpers expose GraphQL error codes and messages. Use hasErrorCode, getErrorMessages, and ERROR_CODES when calling persistedQuery directly.

import { ERROR_CODES, hasErrorCode, persistedQuery } from "heb-sdk-unofficial"

const response = await persistedQuery(session, "cartEstimated", { userIsLoggedIn: true })

if (hasErrorCode(response, ERROR_CODES.UNAUTHORIZED)) {
  await session.refresh?.()
}

---

Use typed classes

The SDK exports HEBError and specific subclasses for app-level normalization. Core calls currently throw plain Error, so treat the classes as optional helpers.

---

Retry safely

Bearer sessions can auto-refresh via session.refresh. For cookie sessions, re-extract cookies when you see 401/403 or UNAUTHORIZED.