Table of Contents

Ticket Widget: Error Responses and Debugging

Helpdocs Admin Updated by Helpdocs Admin

When something goes wrong, the widget shows an error instead of its content. This article explains what counts as an error, how to return one that displays well, and how to find the cause of a problem.

In short: return an error in the standard shape, with a clear message. The user sees the message. The code is for developers and is visible only in the browser's network panel.

What counts as an error

A widget shows an error in these cases:

  1. Your API returns a status code of 400 or higher.
  2. The response doesn't follow the widget specification. The client builds this error itself, because it can't render what it received.
  3. The request fails, for example because of a network failure.

Returning an error

Follow this shape so the error displays correctly:

{
  "error": {
    "code": "asset_not_found",
    "message": "We couldn't find that asset. It may have been removed."
  }
}

Send it with a status code of 400 or higher, for example 404 or 500.

  • message is shown to the user in the widget. Write it for the person reading the ticket: short, plain, and say what to do next if you can. Don't include technical details, ids or stack traces.
  • code is not shown in the UI. Use a stable, searchable value such as asset_not_found. It can be seen in the network panel, so it helps when someone reports a problem.

Use an error for failures only. For expected results, such as an empty list, return a normal response.

If your API returns an error that is not in this shape, or a network failure happens, the client treats it as if no error message was given. The user sees the error layout without your message.

How the error looks

The widget switches to an error layout:

  • Icon: the error icon.
  • Header: a message saying the widget had difficulty displaying.
  • Content: your error message.

You can't change the icon. It isn't part of the error response, so only code and message can be set.

The user can press the refresh button to try again.

When the response breaks the specification

The client checks the structure of a successful response. If the structure is wrong, it shows an error even though the status code was fine.

A structure failure is when a property is missing or has the wrong type. For example:

  • A property that must be a string is a number, an object or null.
  • A required property, such as type or title, is missing.
  • type is missing or isn't one of description, list, progress or form.
  • value doesn't match the type. For example, a list widget whose value isn't a list.

The client builds the error message in this case. Your API doesn't control it.

What is not an error

Limits are not structure failures. If a value is too long, such as a label, the client truncates it and carries on. Extra items beyond a limit are dropped. The widget still displays. See each article for the limits.

Debugging

The most useful thing to do first is save the network record. It holds the request, the response, the status code and the error code.

  1. Open the browser's developer tools and go to the Network panel.
  2. Reload the ticket, or press the action that failed.
  3. Find the request to your widget or action URL.
  4. Save it, for example with "Save all as HAR" or by copying the request and response.

Then check:

  • Status code. 400 or higher means your API returned an error. Read the code and message in the response.
  • Status 200 but an error shown. The response probably breaks the structure. Compare it with the type's article. Look for a wrong type, a missing type or title, or a value of the wrong shape.
  • Request body. Check state and form, and the URL, including its query. See How the Widget Is Requested.
  • Wrong content after an action. Check the action's URL. The provider tells actions apart by route or query, see Actions.
  • Authentication errors. Check that the delegate token is still valid.

When you ask someone for help, attach the saved network record.

How did we do?

Ticket Widget: Form Results and State Across Steps

Ticket Widget: Building a Multi-Step Request

Contact