Nodewood
Build with Nodewood

# Error Handling

Errors emitted by the API follow the JSON API error format (opens new window). An example of an emitted error follows:

{
  "errors": [
    {
      "code": "ERROR_MIN_LENGTH",
      "meta": {
        "minLength": 8,
      },
      "source": {
        "parameter": "password",
      },
      "title": "Password must be at least 8 characters.",
    },
    {
      "code": "ERROR_MATCH_FIELD",
      "meta": {
        "matchField": "password",
      },
      "source": {
        "parameter": "password_repeat",
      },
      "title": "Passwords must match.",
    },
  ],
}

The above example represents a user creation form that failed validation. The password parameter did not meet the complexity requirements (minimum 8 characters in length), and the password_repeat parameter did not match the password parameter.

The code field is a string constant that can be found in wood/lib/Errors and is safe to perform comparisons against, while title is a descriptive string that is safe to display to the user, but is not safe to perform comparisons against, as it may change.

The source field can be used to identify what form field caused the error, and the display the error next to said field. meta is an optional field that can be used to add extra information to the error, as necessary.

# StandardErrors

Also defined in wood/lib/Errors are a series of errors:

  • Standard400Error: A form validation or other user error.
  • Standard401Error: The user has not provided correct authentication.
  • Standard403Error: The user is authenticated, but does not have access to the requested resource.
  • Standard404Error: The request the user is asking for cannot be found.


These errors all follow the same format when created, an array of objects that match the above-mentioned JSON API error format:

throw new Standard400Error([{
  code: ERROR_UNIQUE,
  title: 'You already have a project with that name.',
  source: { parameter: 'name' },
}]);

As these errors all follow the same format, they are exported handled by the same middleware that catches errors of this type and handles outputting the response of the request. To add more errors to this list, add them to the Standard4xxErrors exported by app/lib/Errors:

const { Standard4xxErrors } = require('@wood/lib/Errors');

module.exports = {
  Standard4xxErrors: [
    ...Standard4xxErrors,
    'Standard420Error',
  ],
};

# Display Errors in UI

The simplest way to display errors is to display them in a toast:

import { errorToast } from '#ui/lib/toast';

// ...

try {
  doSomethingThatCanThrowAnError();
}
catch (error) {
  errorToast(error.message);
}

However, if you are using Validators for a form, you can rely on the global errorCaptured handler in App.vue, which will attempt to parse any API errors and store them in the apiErrors field in the data section of your component. Then, if using a component that binds to apiErrors or if manually displaying your apiErrors in your component, any errors returned from the server will "magically" appear in the correct spot on the form.

You can add a manual try/catch around your code if you want to do something special on error handling, but remember to re-throw the error if you still want it to end up being parsed and sorted into the correct apiErrors entry.

A note on error format: if you want to automatically have your error sorted into the correct apiErrors field, you have to have a source.parameter set in the error object:

throw new Standard400Error([{
  code: ERROR_EMPTY,
  title: 'You must enter your name.',
  source: { parameter: 'name' },
}]);

Errors that do not have a source.parameter field set will instead be displayed as an error toast. So if you are returning an error that doesn't have a specific field that it lines up with (say, because a 3rd-party API call failed, for example), no worries! Just omit the source parameter entirely and it will still be displayed.

← Introduction →