errorHandler

The errorHandler submodule helps you monitor, track, and cover errors in your app or site, and provides default content for common errors. This allows you to replace generic error messages with meaningful, actionable feedback for Wix users.

Custom error content

When you wrap SDK backend modules or httpClient.fetchWithAuth() calls with the withErrorHandler() hook, you can define custom content and actions for specific errors that can occur during the request.

The hook maps the returned response to an error message according to either the custom error mapping you provide, or the default error content. You can display the error message to a Wix user with the showError() or getResolvedError() method.

You retain the ability to catch the error, handle additional logic in the catch block, and show the errors to Wix users. The errorHandler module gives you flexibility while ensuring that each request has tailored error handling with clear, actionable feedback.

Default error content

In addition to handling custom errors, the ErrorHandler provides default content for common error codes:

The relevant content for each error is automatically attached when the error occurs, but you can override the content in the error codes map and options if needed.

Displaying the errors

Once you catch an error, you have two options for handling it:

• Use the default showError() function: This function displays the error to the Wix user in a default UI using the appropriate content and actions.

• Customize your own UI: Use getResolvedError() to retrieve the relevant error content and display it to the Wix user in a custom UI.

Import statement

Methods

withErrorHandler()

Wraps requests with standardized error handling. It provides a consistent way to manage different types of errors using a configurable error mapping:

• An error code map for handling standard Wix application and validation errors.
• Options for handling specific HTTP status codes.
• Options for handling all server errors in one configuration.

Method Declaration

Parameters

Returns

A promise that resolves with the response or rejects with a customized error.

Example

getResolvedError()

Resolves errors into a standardized format that you can use in your custom UI for consistent error handling and messaging.

If the specific error code was not mapped in withErrorHandler, this function will return a pre-defined message based on the HTTP status code, as described in the Built-in Error Content section.

Method Declaration

Parameters

Returns

A ResolvedError object. The Partial<T> in the return type allows access to any additional properties that were passed to ShowErrorProps in withErrorHandler.

Example

showError()

Displays a standardized error message to the Wix user. It merges error details with optional custom properties and returns the error to the user with the Wix platform's default display mechanism and UI.

If the specific error code was not mapped in withErrorHandler, this function displays a pre-defined message based on the HTTP status code, as described in the Built-in Error Content section.

Method Declaration

Parameters

Example

Properties

ErrorCodesMap

Maps application and validation errors to error handling functions.

ShowErrorMapFunction

Returns error display properties.

StatusCodeMap

Maps HTTP status codes to error handling functions.

StatusCode

String literal union type representing HTTP status codes.

Objects

ShowErrorProps

WithErrorHandlerOptions

ResolvedError

Action

Examples

Direct Auto-Completion with SDK Functions

When you pass a typed SDK function to withErrorHandler, TypeScript automatically provides auto-completion for the error codes that function can return:

Using ErrorCodesMap with Type Arguments

For more advanced scenarios or when defining error maps separately, you can use the generic ErrorCodesMap type with a function type argument to get explicit auto-completion:

Advanced Example with Custom Properties

This example shows how to use getResolvedError with additional custom properties that extend ShowErrorProps:

Example with httpClient.fetchWithAuth

This example demonstrates using withErrorHandler with httpClient.fetchWithAuth for making authenticated HTTP requests. Unlike SDK functions, fetchWithAuth does not throw on unsuccessful HTTP responses but still throws on network errors. This is why you need to check response.ok and use the response object as an error when the request fails:

Key differences from SDK usage:

• fetchWithAuth returns a Response object even for HTTP error status codes (4xx, 5xx).
• You must check response.ok to determine if the request was successful.
• The response object itself is passed to showError() when response.ok is false.
• Network errors like connection issues or timeouts still throw and are caught in the catch block.

For more information about making authenticated requests, see the httpClient documentation.