Widget error codes

The TeakOS Widget logs these codes to the browser console. Your callbacks don't receive them, so check the console when debugging. When any of them happens, the widget removes itself so the customer can check out without protection, except E4014, where the widget carries on. See what happens when the widget fails.

Configuration errors mean the configure call is invalid: fix them during development. Runtime errors happen while the widget runs and are usually temporary.

No code, but no offer either? See When there's no error but no offer.

Runtime errors

E4001

Couldn't load the offer. The customer sees: no offer. The widget removes itself.

E4001 - Something went wrong fetching the widget's configuration.

The widget couldn't load its configuration or price the cart. Usually this is a key that doesn't match the environment, or Teak being briefly unreachable.

How to fix it

• Check apiKey is your public key (pk_...), not your secret key.
• Check the key matches the environment: sandbox keys need sandbox: true, production keys need it omitted.
• If it's intermittent, it's temporary. Let the customer check out without protection. Check status.helloteak.com for incidents affecting the TeakOS Widget.

Sandbox key without sandbox: true:

teak('configure', {
  apiKey: 'pk_sandbox_...',   // sandbox key
  // sandbox: true is missing, so the widget calls production
  items: [/* ... */],
});

teak('configure', {
  apiKey: 'pk_sandbox_...',
  sandbox: true,
  items: [/* ... */],
});

E4002

Couldn't save the customer's choice. The customer sees: the offer disappears after they choose.

E4002 - Something went wrong updating the existing session.

The widget couldn't save the customer's opt-in or opt-out to Teak. This happens when Teak is briefly unreachable, or when the session was already submitted. A submitted session can't change.

How to fix it

• Call teak('clearSession') after every completed checkout. A second purchase that reuses a submitted session fails with this error.
• Otherwise it's temporary. Let the customer check out without protection. Check status.helloteak.com for incidents affecting the TeakOS Widget.

Missing clearSession after checkout:

// Order confirmation page
showConfirmation(order);
// The session was submitted, but it's still in the browser.

// Order confirmation page
showConfirmation(order);
teak('clearSession');

E4003

Choice rejected. The customer sees: the offer disappears after they choose.

E4003 - We could not update your selection. Please refresh and try again.

Teak rejected the customer's choice, usually because the cart changed while the choice was being saved, so it referred to items that are no longer in the quote.

How to fix it

• Avoid calling configure with a new cart at the same moment the customer is choosing, for example by re-rendering on every keystroke in a quantity field.
• Let the customer check out without protection. Reloading the page shows a fresh offer.

E4004

Too many requests. The customer sees: the offer disappears after they choose.

E4004 - Order items PATCH rate limited.

Saving the customer's choice was rate-limited. The widget already retried up to 3 times, waiting as Teak asked, before giving up.

How to fix it

• Check your page isn't calling configure in a loop, which re-prices the cart repeatedly.
• Let the customer check out without protection.

Configuration errors

E4010

Missing API key. The customer sees: no offer.

E4010 - The "configure" command must receive an "apiKey" option with a valid value.

configure (or preload) was called without apiKey, or with an empty value.

How to fix it

• Pass your public key (pk_...) as apiKey in every configure call, including after clearSession, which resets the widget's options.

apiKey missing:

teak('configure', {
  items: [/* ... */],
});

teak('configure', {
  apiKey: 'pk_...',
  items: [/* ... */],
});

E4011

No options passed. The customer sees: no offer.

E4011 - Options must be passed in with the "configure" command.

configure was called with no options object.

How to fix it

• Pass an options object with at least apiKey and items.

No options:

teak('configure');

teak('configure', {
  apiKey: 'pk_...',
  items: [/* ... */],
});

E4014

Invalid session ID. The customer sees: the offer, as normal.

E4014 - The "configure" command received an invalid "sessionId" ("not-a-uuid"). It must be a canonical UUID: 8-4-4-4-12 hexadecimal (uppercase is accepted and stored lowercased).

The sessionId you passed to configure isn't a UUID in its standard form. The widget ignores it and keeps the session it already has, so the rest of your configure call still applies.

How to fix it

• Pass a UUID in groups of 8-4-4-4-12 hexadecimal characters, for example from crypto.randomUUID().
• Or leave sessionId out, and the widget creates its own.

Not a UUID:

teak('configure', {
  apiKey: 'pk_...',
  sessionId: 'order-1001',
  items: [/* ... */],
});

teak('configure', {
  apiKey: 'pk_...',
  sessionId: crypto.randomUUID(),
  items: [/* ... */],
});

E4020

Both costsOfItems and items passed. The customer sees: no offer.

E4020 - The "configure" command cannot simultaneously receive both the "costsOfItems" and "items" options.

The call passed costsOfItems, an option from Teak's earlier widget, alongside items.

How to fix it

• Remove costsOfItems. The TeakOS Widget only uses items.

costsOfItems alongside items:

teak('configure', {
  apiKey: 'pk_...',
  costsOfItems: [120],
  items: [{ name: 'GA Ticket', referenceNumber: 'ITEM-1', cost: 120, event: { location: 'Austin, TX' } }],
});

teak('configure', {
  apiKey: 'pk_...',
  items: [{ name: 'GA Ticket', referenceNumber: 'ITEM-1', cost: 120, event: { location: 'Austin, TX' } }],
});

E4021

No items. The customer sees: no offer.

E4021 - The "configure" command must receive a "costsOfItems" option or an "items" option with a populated array of values.

items is missing or empty.

How to fix it

• Pass at least one item. If the cart is empty, don't call configure until it has items.

Empty cart:

teak('configure', { apiKey: 'pk_...', items: [] });

if (cart.lines.length > 0) {
  teak('configure', { apiKey: 'pk_...', items: toTeakItems(cart) });
}

E4022

Invalid item cost. The customer sees: no offer.

E4022 - The "items" option must receive finite cost values: a finite number or a numeric string.

An item's cost isn't a finite number or a numeric string, for example '$120', 'free', or NaN.

How to fix it

• Pass cost as a number (120) or a numeric string ('120.00'), without currency symbols. Set the currency with the currency option.

Formatted cost:

items: [{ name: 'GA Ticket', referenceNumber: 'ITEM-1', cost: '$120.00', event: { location: 'Austin, TX' } }]

items: [{ name: 'GA Ticket', referenceNumber: 'ITEM-1', cost: 120.0, event: { location: 'Austin, TX' } }]

E4024

Item missing cost. The customer sees: no offer.

E4024 - Every item object in the "items" option must include a "cost" key.

An item in items has no cost.

How to fix it

• Add cost to every item: the price of one item, in currency.

No cost:

items: [{ name: 'GA Ticket', referenceNumber: 'ITEM-1', event: { location: 'Austin, TX' } }]

items: [{ name: 'GA Ticket', referenceNumber: 'ITEM-1', cost: 120, event: { location: 'Austin, TX' } }]

E4025

costsOfItems not supported. The customer sees: no offer.

E4025 - The "configure" command for ICW Elements must receive an "items" option with full item objects (including "name" and "referenceNumber"); "costsOfItems" is not supported.

The call passed costsOfItems, an option from Teak's earlier widget, instead of items.

How to fix it

• Replace costsOfItems with items, passing a full object for each item.

costsOfItems:

teak('configure', { apiKey: 'pk_...', costsOfItems: [120, 120] });

teak('configure', {
  apiKey: 'pk_...',
  items: [
    { name: 'GA Ticket', referenceNumber: 'ITEM-1', cost: 120, event: { location: 'Austin, TX' } },
    { name: 'GA Ticket', referenceNumber: 'ITEM-2', cost: 120, event: { location: 'Austin, TX' } },
  ],
});

E4026

Item missing name or referenceNumber. The customer sees: no offer.

E4026 - Every item object in the "items" option must include non-empty "name" and "referenceNumber" strings (index 0).

An item is missing name or referenceNumber, or one of them is empty. The message gives the item's position in items.

How to fix it

• Add both, as non-empty strings.
• referenceNumber is your ID for the item. It comes back in webhooks, so make it unique per item, for example by adding a suffix for each ticket in a line.

No referenceNumber:

items: [{ name: 'GA Ticket', cost: 120, event: { location: 'Austin, TX' } }]

items: [{ name: 'GA Ticket', referenceNumber: 'ITEM-1', cost: 120, event: { location: 'Austin, TX' } }]

E4027

Missing event location. The customer sees: no offer.

E4027 - Every item object in the "items" option must include a non-empty "event.location" string.

An item has no event.location, or it's empty. Teak uses the location to price and cover the item.

How to fix it

• Add event.location to every item, for example the venue's city and region.

No event location:

items: [{ name: 'GA Ticket', referenceNumber: 'ITEM-1', cost: 120, event: { name: 'Summer Fest' } }]

items: [{ name: 'GA Ticket', referenceNumber: 'ITEM-1', cost: 120, event: { name: 'Summer Fest', location: 'Austin, TX' } }]

Next steps

To handle widget failures in your checkout:

• Learn what happens when the widget fails and what to do about it.
• Handle the customer's choice to keep your order total right, keep the widget in step with the cart, and handle errors.