REST error handling
REST errors returned by the endpoints in an app are often too technical for end-users to comprehend. Jigx allows you to customize these error messages to improve user experience, communicate more effectively, and ensure users understand that errors are not their fault. By configuring custom error handling, you can:
- Suppress or customize default error messages.
- Log error details for more effective debugging.
- Create more robust and user-friendly error solutions.
- Custom error messages: Control the message shown to users when a REST error occurs.
- User-friendly retry options: Allow users to retry an action when an error occurs.
- By default, automatically catches any 429 error responses and retries the request up to three times, with a five-second delay between each attempt.
- Error logging: Automatically log error details for debugging.
- Dynamic responses: Build logic to respond to specific errors flexibly.
In Jigx, REST error handling is configured through an error section in the REST function. This allows the system to catch various error responses and act accordingly:
- Multiple error responses can be defined and are evaluated in sequence.
- Error responses can trigger notifications, log errors, or provide retry options for users.
- The app supports customized messaging for each error type.
- Expressions are supported in functions.
High level steps:
- Configure the error section in the REST function to customize the error message and configure an error table.
- Create a datasource for the error table.
- Create a UI () to process the error in the queue using the commandQueue actions.
By default, Jigx automatically handles 429 (Too Many Requests) error responses for CRUD and sync methods by retrying the request up to three times, with a five-second delay between each attempt. If the request still fails after the third retry, the error is raised in the app. You can customize this behavior by configuring the handling of the 429 status in the error property.
In the function, configure the error section to cater for:
- Customizing the error message.
- Determining if a toast notification is required or not.
- Writing the context of the error to a table for debugging and configuring actions to fix the error.
Multiple error handlers can be added in the function, which are executed from the top to bottom until one matches. The error section needs to be configured in each of the individual REST function files.
The following properties are available for configuration when handling REST errors:
Property | Description |
---|---|
description | Provide a user friendly message of the error, for example, "It looks like our system is unavailable." Defaults to the provider's description if absent. For example, the REST provider uses the HTTP status code and message. The description property supports localization. |
details | Add additional information that will display under the description. Defaults to the provider's details if absent. |
icon | Select an icon to show on the error notification screen. |
notification | Determines whether the notification should be shown on the device. (true/false) |
retry | Provides the ability to configure an automatic retry, set a delay time before the retry is executed and specify the maximum number of retries allowed. By default, Jigx automatically handles 429 (Too Many Requests) error responses for CRUD and sync methods by retrying the request up to three times, with a five-second delay between each attempt. If the request still fails after the third retry, the error is raised in the app. You can customize this behavior by configuring the handling of the 429 status in the error property. |
table | Define a table where the error information specified in the transform property will be logged to, for example: table: [email protected] & "_error" |
title | Title that displays on the toast notification. Defaults to the provider's title if not provided. The title property supports localization. |
transform | Specifies the details to log in the table for the error, such as the request, response, and user context, for example: '={ "id": @ctx.commandId, "type": "System Offline", "screen": "system-offline", "response": @ctx.response, "request": @ctx.request, "user": @ctx.user, "solution": @ctx.solution, "entity": @ctx.entity, "correlationId": @ctx.correlationId}' |
when | Checks if the result of the function is an error, the first one that resolves to true is used. - The REST provider uses a combination of actual errors encountered and the HTTP status code and message. Configure different types of actions depending on the error received, by using multiple when statements. - If the property is not configured it defaults to the REST provider's default error check. |
Example configuration:
Logging errors is a crucial part of the error handling mechanism. Errors are logged into a dedicated error table defined by you, capturing key information for debugging and analysis. Take the information that you currently have in the context of the function and log it to the table by defining the data to be logged in the transform property.
- The full error coming back from the backend system should be logged.
- Expose error tables in to help with troubleshooting.
- Define a datasource against the error tables.
Error logging configuration:
When configuring REST errors, several system expressions and variables can be used. These variables allow you to dynamically log and handle errors based on the context of the function call.The following context is available to write to the error table, using [email protected]:
Variables | Value |
---|---|
commandId | Unique id logged for the item on the commandQueue. The id matches the id in the entity table. |
correlationId | The unique identifier that appears in the app. It is used in troubleshooting to help identify specific entries in the logs and to follow the user's journey while using the solution in the app. By filtering logs using this ID, you can troubleshoot issues more effectively. |
entity | The specified table where the error context is logged |
error |
|
parameters | Specify any of the parameters in the function to be logged to the error table. |
request |
|
response |
|
solution |
|
user |
|
The commandQueue is a system table, when a device is offline items are queued on the table. When the device comes online the items in the queue are processed. However, if items on the queue go into error, they are not processed and remain on the queue. Errors from REST methods, except for action.sync-entity/entities are queued in the commandQueue table. The commandQueue is exposed in Dev tools, allowing you to debug . You can expose the commandQueue table in a and then use the commandQueue actions to interact with the queued items that are in error state by either performing a retry or delete. Take note that when syncing an item or when the device is offline the commandId is not available.
There are two actions related specifically to the commandQueue namely:
- action.retry-queue-command - executes a retry of the REST function called.
- action.delete-queue-command - Only deletes the item from the commandQueue. The record will still be saved locally on the device. You need to provide separately for the deleting of the local data, which can be achieved through an action.sync-entity/entities or executing a delete method on the local data provider.
Action configuration:
- The commandId matches the id in the error table, this is important when you want to build a /UI to deal with the error.
- When using the commandQueue actions the commandQueue id (commandId) is required.
- Use the error table to build a /UI as there is more data logged to the table than the commandQueue.
- Use the _commandQueue table as a datasource in your solution. It behaves like a normal entity table with change events and updates.
- When useLocalCall: true is set, functions that rely on secrets or other authentication mechanisms not available locally will not execute.
See REST error example to understand how to configure error responses in a REST function, create a error table and use the commandQueue with actions to process the error.