Error Handling

There are two categories of errors that may occur during execution of the invoke method:

  • Invalid requests due to faulty parameters or configuration

  • Runtime errors caused by some fault in the API or service driver

Invalid Requests

When this type of error occurs, the information should propagate up to the API so whoever invoked the service can see what the error was. A typical case for this is when the authentication token provided in the configuration is invalid. To throw these kind of errors, use the WebServiceError class:

import { WebServiceError, SimpleMap } from '@sirensolutions/web-service-interface'

  invoke(params: object): Promise<SimpleMap> {
    return fetchResults(params)
      .catch(err => Promise.reject(err.response.status < 500 ? new WebServiceError(err.response.data) : err));
  }

This class accepts any parameter in its constructor. This data gets passed up to the API so the person invoking can be informed:

{
  "type": "bad_request_to_web_service",
  // 'data' will be set to whatever is passed into the WebServiceError constructor
  "data": {
    "error_type": "AUTHENTICATION",
    "message": "Authentication token is not valid"
  },
}

Note that invocations with parameters that do not conform to the inputSchema are rejected automatically.

Runtime Errors

This type of error includes programming errors and unexpected responses from the external service. Because they do not happen due to the fault of the person invoking, they should not propagate up to the API, but rather be handled by the system administrator who installed the web service drivers. Any error that is thrown by the invoke method that is not a WebServiceError is treated as a runtime error and results in the following being returned from the API:

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An internal server error occurred"
}

And a stacktrace being printed to the Investigate logs:

server   error  [16:37:23.320]  Error: 503 Service Temporarily Unavailable
    at MyService.fetchResults (../src/my-service-group/MyService.ts:87:15)
    at MyService.invoke (../src/my-service-group/MyService.ts:42:11)
    at WebService.invokeEphemerally (../src/server/service_manager/WebService.ts:78:33)
    at WebService.invokeAndStore (../src/server/service_manager/WebService.ts:71:17)