@flytio/int-error-helper

Error helper for integrations

Use this package to standardize the error codes and make good and actionable error messages for order injection failures.

The method exported by this package will help you to build the error object on the OrderResponse that must be returned by the gRPC methods in the order integration.

The package also supports overriding the default Escalation Path of errors. This allows us to automatically alert the relevant party during an incident and improve our oncall experience.

NOTE: This helper is only working for the order integrations at the moment, but the name has been left generic because it could easily be extended to cover the sync menu errors in the future.

What is an actionable error message?

An error message should contain as much information as possible to help who responds to the error to take an action to promptly fix it.

A bad error message, for example, is the following:

There was an unknown error sending the order to the POS.

While a good one is, for example:

There is an invalid item in the payload, please contact the menu team to confirm the PLUs are correct. POS Error message: [-956234774] Invalid database object detected: 1234

This message is composed by three parts:

1. A text explaining the error occurred
2. Who need to be contacted to investigate / fix the problem
3. The original POS error message

With a well defined error message like the above one, who spots the error knows immediately what the problem is and how to act in order to fix it.

Why using an npm module for that?

We decided to create a module in order to unify the error codes and messages returned by the various integrations. We want, for example, that the error messages for an invalid tender type to be the same across all the integrations.

When I should use this module?

You should use this module in every integration you're developing. What you need to do on your integration is investigating on the error response returned from the POS and call this module methods that will create the error object (required in the OrderResponse) for you, with no hassle required to make sure they are the same all across the integrations.

Usage

Install

Install the package using yarn:

yarn add @flytio/int-error-helper

How to use in your integration

In order to use this helper in your integration, you must first register it.

import { IntegrationErrorMapper } from '@flytio/int-error-helper';

const integrationErrorMapper = new IntegrationErrorMapper();

Once you have your helper instantiated, you can use the fromErrorResponse method to build the error object of an OrderResponse:

import { OrderResponseStatus } from '@flytio/protos';
import { knownErrors } from 'constants/known-errors.ts';

return {
  status: OrderResponseStatus.Rejected,
  can_retry: false,
  happened_at: `${Date.now() / 1000}`,
  error: integrationErrorMapper.fromErrorResponse(
    response.err.message,   // Original POS error message or code
    knownErrors             // Array of known errors for that integration
  ),
};

Known Errors:

Some integrations would always return 200 OK even for errors. In such cases developers will need to parse the error from the response body and try to classify it. You might need to check the POS documentation or even the Kibana error logs to understand what possible errors can be returned and group them by ErrorCode.

int-error-helper requires you to pass an array with KnownErrors when building the error.

import { ErrorCode, EscalationPath } from '@flytio/protos';
import { KnownErrors } from '@flytio/int-error-helper';

const knownErrors: KnownErrors = [
  {
    message: 'Example Menu Error With Explicit Escalation',
    errorCode: ErrorCode.MenuError,
    escalationPath: EscalationPath.Partner, // Override the default escalation path for that error code
  },
  {
    message: 'Example Menu Error No Escalation Path',
    errorCode: ErrorCode.MenuError,
    customAction: 'The menu PLUs are incorrect, try sync the menu again', // Override the default error message
  },
  {
    message: 'Example MalformedRequest Error',
    errorCode: ErrorCode.MalformedRequest,
  },
  {
    message: ['Example Multi line error', '-11013'], // Both strings must be included in the original error
    errorCode: ErrorCode.MalformedRequest,
  },
  {
    message: 'Example IncorrectSetup Error',
    errorCode: ErrorCode.IncorrectSetup,
  },
  ...
];

In the example above:

• message is the original error message returned from the POS
• errorCode is one of Flyt's Error Codes defined in the protos
• escalationPath is an optional parameter that will overwrite the default escalation path for incidents with that Error Code (defined in src/constants/constants.ts). Only use this in cases where you are sure about the origin of the error.
• customAction is used to override the error message returned by the error. Please write good error messages, with an action and a subject, as defined here

int-error-helper will try to match the error returned by the POS to list above. The way this currently works is just by checking if the string in your KnownErrors arrays is a substring of the original POS message. If the error returned from the POS doesn't match any of the known errors, int-erorr-helper will default to ErrorCode.Unknown and EscalationPath.Flyt.

Error Codes:

You can use any of the Error Codes defined in the Protos

Escalation Paths:

The Escalation paths currently defined in the Protos are FLYT, POS, BRAND and PARTNER Only use Escalation path different from FLYT if you are confident that particular error is caused by something that is out of our control.

Default error messages and escalation paths

Error Code	Default Error message	Default escalation path
UNKNOWN	Unknown Pos Error, contact the Flyt dev team for support	Flyt
INACTIVE	POS is Inactive, contact the POS company for support	POS
INCORRECT_SETUP	Some configuration parameters are incorrect, check the parameters within the POS and the Flyt portal	Flyt
IN_USE	The POS is currently in use and the order cannot be sent, contact the Flyt dev team for support	Flyt
NOT_SURE	We cannot know if the order went through or not, contact the Flyt dev team for support	Flyt
NOT_SUPPORTED	This functionality is not available on the location selected, contact the Flyt dev team for support	Flyt
MENU_ERROR	There was an error with an item sent to the POS, contact the menu team to confirm the PLUs are correct	Flyt
MALFORMED_REQUEST	The request sent to the POS is malformed, contact the Flyt dev team for support	Flyt
AUTH_FAILED	The authentication request to the POS failed, check if the POS configuration is correct	Flyt
STORE_CLOSED	The store is closed, check the working hours of the restaurant	Partner
TENDER_ERROR	Tender type was not found in POS, contact the POS company for support	Flyt

Migrating from version 1.X.X to 2.X.X

Version 2.X.X introduces breaking changes to this service.

In version 1.X.X you would pass the original POS message as well as one of the default error codes supported by the helper.

const error = integrationErrorResponse.buildFor(
  defaultErrors.MalformedRequest,
  'This is what happened in the POS'
);

From version 2.X.X you would need to pass the original POS message as well as an array of KnownErrors (interface exported by int-error-helper). The defaultErrors and the registerNewError functionality from version 1.X.X have been removed, as you can now use any error code defined in Protos. More information can be found in the Known Errors and Error Codes sections of this README

const error = integrationErrorMapper.fromErrorResponse(
    'This is what happened in the POS',
    knownErrors
  );