Proxy Transform Error Handling

Error handling in proxy transforms differs based on the runtime you're using. When an error occurs, the proxy request is terminated and the HTTP response is immediately returned. In particular, errors from a request transform will cause the proxy request to terminate before calling the destination API.

node-bt Error Handling

In node-bt, errors are handled by throwing reactor errors from your transform code.

Standard Error Responses

All pre-defined reactor error types, excluding errors of type CustomHttpResponseError, will be returned in their standard format and wrapped in a proxy_error property to distinguish these errors from destination API errors. When thrown from a request transform, these errors will skip forwarding the request to the destination.

For example, a transform containing the following code:

const { AuthenticationError } = require('@basis-theory/basis-theory-reactor-formulas-sdk-js');

module.exports = async function (req) {
    const apiKey = req.args.headers['MY-CUSTOM-API-KEY'];

    if (!apiKey)
        throw new AuthenticationError('MY-CUSTOM-API-KEY header is required');

    // ...
}

would result in the following error response with a 401 status code if the MY-CUSTOM-API-KEY header is omitted:

{
    "proxy_error": {
        "errors": {
            "error": [
                "MY-CUSTOM-API-KEY header is required"
            ]
        },
        "title": "One or more validation errors occurred.",
        "status": 401,
        "detail": "Authentication Failed"
    }
}

Note that errors are wrapped in a proxy_error property to distinguish them from destination API errors.

Custom Error Responses

To bypass the proxy_error wrapper and have full control over the response (status code, headers, and body), use CustomHttpResponseError. When thrown from a request transform, this will skip forwarding the request to the destination and return your custom response directly:

const { CustomHttpResponseError } = require('@basis-theory/basis-theory-reactor-formulas-sdk-js');

module.exports = async function (req) {
  throw new CustomHttpResponseError({
    status: 400,
    headers: {
        "Custom-Response-Header-1": "custom-value-1",
        "Custom-Response-Header-2": "custom-value-2"
    },
    body: {
        myCustomError: "My custom error message"
    }
  });
};

This results in an API response with status code 400, having the specified headers and response body without the proxy_error wrapper:

{
    "myCustomError": "My custom error message"
}

Uncaught Errors

Any other errors raised from your node-bt transform code (that are not one of the standard reactor error types) will result in a ReactorRuntimeError containing the original error object and the response will have status code 500, wrapped in the proxy_error property.

To provide better error handling, catch exceptions in your code and throw appropriate reactor error types.

Best Practices

• Handle errors appropriately using the standard reactor error types
• Use CustomHttpResponseError when you need to bypass the proxy_error wrapper
• Consider when to use standard errors vs custom errors based on your API design
• Catch and handle all potential errors to provide clear error messages

Examples

Error handling examples for node-bt transforms are shown in the Standard Error Responses and Custom Error Responses sections above.

node22 Error Handling

In node22, errors are handled by returning a response object with the desired status code and error details. There is no proxy_error wrapper. The response body you return is sent directly to the client.

Standard Error Responses

Return a response object with statusCode and body to handle errors. The response format is exactly what you specify. There is no automatic wrapping. When returned from a request transform, this will skip forwarding the request to the destination.

For example, a transform containing the following code:

module.exports = async function (event) {
  const { headers } = event.req;
  const { logger } = event;

  if (!headers['MY-CUSTOM-API-KEY']) {
    logger.warn("Authentication failed: missing API key");
    return {
      res: {
        body: { error: "MY-CUSTOM-API-KEY header is required" },
        statusCode: 401
      }
    };
  }

  // ...
};

would result in the following error response with a 401 status code if the MY-CUSTOM-API-KEY header is omitted:

{
    "error": "MY-CUSTOM-API-KEY header is required"
}

Custom Error Responses

In node22, you always have full control over error responses. Simply return the desired statusCode, headers, and body in your response object. There is no wrapper or special error type needed. The response you return is sent directly to the client. When returned from a request transform, this will skip forwarding the request to the destination.

For example:

module.exports = async function (event) {
  return {
    res: {
      statusCode: 400,
      headers: {
        "Custom-Response-Header-1": "custom-value-1",
        "Custom-Response-Header-2": "custom-value-2"
      },
      body: {
        myCustomError: "My custom error message"
      }
    }
  };
};

This results in an API response with status code 400, having the specified headers and response body:

{
    "myCustomError": "My custom error message"
}

Uncaught Errors

If an uncaught error is thrown from your node22 transform code (e.g., a runtime exception that isn't caught), it will result in a 500 status code with a generic error response. To provide better error handling, wrap your code in try/catch blocks and return appropriate error responses:

module.exports = async function (event) {
  const { req, logger } = event;

  try {
    // Your processing logic here
    if (!req.card_number) {
      return {
        res: {
          body: { error: "card_number is required" },
          statusCode: 400
        }
      };
    }

    return {
      res: {
        body: { success: true },
        statusCode: 200
      }
    };
  } catch (error) {
    logger.error("Processing failed", { error: error.message });
    return {
      res: {
        body: { error: "Internal error" },
        statusCode: 500
      }
    };
  }
};

Best Practices

• Handle errors appropriately by returning error responses with suitable status codes
• Include clear error messages in the response body
• Use try/catch blocks to handle unexpected errors
• Return appropriate HTTP status codes (400, 401, 403, 500, etc.)
• Include error details that help with debugging

Examples

Error handling examples for node22 transforms are shown in the Standard Error Responses and Custom Error Responses sections above.

All transforms execute in array order. On the first error, remaining transforms are not executed, and the error response is returned.