Skip to main content

Error Events

Error events track failures during the initialization and data fetching of the Mimeeq <mmq-embed> element. These events are dispatched on document and bubble to window, allowing you to catch template, configuration, and API failures.

Error Flow​

  <mmq-embed> component loads
       │
       ▼
  mimeeq-app-loaded
       │
       ▼
  ┌─── Initialization / Loading ─────────────────────────────────┐
  │                                                              │
  │  Fetching Template:                                          │
  │  (success) ──► Template applied                              │
  │  (fail)    ──► mimeeq-app-template-error                     │
  │                                                              │
  │  Fetching Configs (embed_data, customers):                   │
  │  (success) ──► Config loaded                                 │
  │  (fail)    ──► mimeeq-app-config-error                       │
  │                                                              │
  │  Fetching API Data (observers):                              │
  │  (success) ──► Observer data processed                       │
  │  (fail)    ──► mimeeq-api-error                          │
  └──────────────────────────────────────────────────────────────┘

Events​

mimeeq-app-template-error​

Fires if the template identifier provided to the <mmq-embed> element cannot be loaded. If the template doesn't exist or fails to load, the embed component will stop loading and this event will fire.

This also fires if a Custom UI template (associated with the customUiId inside the embed template) fails to load.

Payload: AppTemplateErrorEventPayload

FieldTypeDescription
errorError | unknownThe thrown error object from the failed fetch
document.addEventListener('mimeeq-app-template-error', (event) => {
  const { error } = event.detail;
  console.error('Failed to load Mimeeq template:', error);
  fallbackToDefaultImage();
});

mimeeq-app-config-error​

Fires if the embed_data or customers configuration JSON files fail to load. These files rely on the short-code passed to the embed. Without them, the configurator cannot render.

It also fires with type: 'embed_data' when a standard or modular embed cannot load its primary product after the existing CDN/API fallback completes, including unavailable or inactive products. A CDN miss followed by a successful API response does not report an error. Cancelled and superseded product requests do not report an error. Reporting does not change the product loader's return values, loading states, or preview behavior. Standard-product preparation errors are also reported while preserving their original rejection.

Runtime script failures emit type: 'embed' (Shopify: APP_NOT_LOADING). Observing a failed script does not settle its existing loading promise or start a retry. Custom UI asset failures and metadata with no usable version emit mimeeq-app-template-error without changing template/loading gates.

Payload: AppConfigErrorEventPayload

FieldTypeDescription
errorError | unknownThe thrown error object from the failed fetch
type'embed_data' | 'customer_data' | 'short_code' | 'embed'Identifies the configuration, shortcode or runtime failure
document.addEventListener('mimeeq-app-config-error', (event) => {
  const { error, type } = event.detail;
  console.error(`Failed to load ${type} config:`, error);
});

mimeeq-api-error​

Fires when an existing fetch/observer request or a shared Axios service request fails. Shared services also include requests made by the admin application. Ignored failures and cancellations do not emit it. The canonical name is mimeeq-api-error; mimeeq-app-api-error is not an alias.

The native event bubbles from document to window; it is not forwarded to a parent frame. Existing fetch errors retain their unknown error value. Shared Axios failures expose a scalar error message and optional status/code metadata, without headers or raw request configuration.

Payload: AppApiErrorEventPayload

FieldTypeDescription
errorError | unknownExisting fetch error value, or scalar Axios error message
requestPathstring (optional)The API path that failed
statusnumber (optional)Axios HTTP status, 504 for timeout, or 0 when unknown
codestring (optional)Axios error code, when available
document.addEventListener('mimeeq-api-error', (event) => {
  const { error, requestPath } = event.detail;
  console.warn(`Mimeeq API call to ${requestPath} failed:`, error);
});