View on GitHub

Whiteflag API

Reference implementation of the Whiteflag protocol as a web API in Node.js to connect applications with the underlying blockchains

Whiteflag API Error Handling

In addition to the standard Node.js JavaScript Error class, two additional classes are exposed by lib/common/errors.js to handle processing and protocol errors. The ProcessingError class is to be used for processing errors, i.e. operational errors that can and must be expected, such as dealing with malformed data or bad client requests. The ProtocolError class is for the handling of Whiteflag message format and protocol errors.

Usage of error classes

The best way to define one or both Whiteflag API error classes within a specific module, is to require the errors module and use an object destructor as follows:

const { ProcessingError, ProtocolError } = require('./common/errors.js');

Both classes use a similar constructor:

err = new ProcessingError(message, causes, code);
err = new ProtocolError(message, causes, code);

with the folloing arguments:

ProcessingError class error codes

ProtocolError class error codes

Guideline for errors, logging and responses

The following table is a guideline on how error codes, log levels and http response codes generally correspond if used in combination.

Error Class Error Code Loglevel HTTP Status Code
Error WF_API_INTERNAL_ERROR level 2: error 500
  WF_API_MIDDLEWARE_ERROR level 5: debug (any)
ProcessingError WF_API_PROCESSING_ERROR level 2: error 400
  WF_API_BAD_REQUEST level 5: debug 400
  WF_API_NOT_ALLOWED level 5: debug 403
  WF_API_NO_DATA level 5: debug 404
  WF_API_NO_RESOURCE level 5: debug 404
  WF_API_RESOURCE_CONFLICT level 5: debug 409
  WF_API_NOT_IMPLEMENTED level 5: debug 501
  WF_API_NOT_AVAILABLE level 3: warn 503
ProtocolError WF_PROTOCOL_ERROR level 5: debug 400
  WF_METAHEADER_ERROR level 5: debug 400
  WF_FORMAT_ERROR level 5: debug 400
  WF_REFERENCE_ERROR level 5: debug 400
  WF_AUTH_ERROR level 5: debug 400
  WF_SIGN_ERROR level 5: debug 400
  WF_ENCRYPTION_ERROR level 5: debug 400