Write Plugins v1.x

You are currently looking at the documentation of a previous version of Kuzzle. We strongly recommend that you use the latest version. You can also use the version selector in the top menu.

Errors Manager #

When creating a Kuzzle plugin, custom API errors can be defined and thrown, using the errorsManager.

Custom errors have to be specified in the manifest.json, in an errors field.


Copied to clipboard!
    "name": "<plugin name>",
    "kuzzleVersion": ">=1.0.0 <2.0.0",
    "errors": {
        "some_error": {
            "code": 1,
            "message": "An error occurred: %s",
            "class": "BadRequestError",
            "description": "Short and understandable error description"
        "some_other_error": {
            "code": 2,
            "message": "An other error occurred: %s",
            "class": "ForbiddenError",
            "description": "Short and understandable error description"

The errorsManager provides two functions:

  • To throw : context.errorsManager.throw(error, placeholders);.
  • To get the built error: context.errorsManager.get(error, placeholders);

Note that the domain is plugin, meaning that its code is fixed to 04 and cannot be changed. By default, the subdomain code for plugins is set to 0. A subdomain can be defined for a plugin in its configuration section in the kuzzlerc file.

Example, for a plugin name foobar-plugin:

Copied to clipboard!
  "plugins": {
    "foobar-plugin": {
      "option_1": "option_value",
      "option_2": "option_value",
      "_pluginCode": 42

Example #

Taking the configuration example above, if an error is thrown with:

context.errorsManager.throw('some_error', 'request badly formatted');

Then when triggered on an API request, Kuzzle will respond to the querying user with a BadRequestError error, with the following properties:

  • message : An error occured: request badly formatted
  • errorName : plugin.foobar-plugin.some_error
  • code : 0x04020033