Error Definitions (BeemM)

This package provides canonical error codes and helpers for building consistent error responses across services.

Start here

• Consumer guide: see CONSUMER_GUIDE.md for real-world usage patterns (API boundaries, middleware, service-to-service errors, dependency failures, and expected response shapes).

Quick start

Create/throw canonical errors in your service code:

import { createError } from "error-definitions";

throw createError("API_INVALID_REQUEST_FORMAT", {
  context: { source: "request-body" },
  traceId,
});

Normalize any unknown error at the boundary (and use status_code as the HTTP status):

import { toErrorResponse } from "error-definitions";

const payload = toErrorResponse(err, { traceId });
res.status(payload.status_code).json(payload);

CommonJS support (require)

This package supports both ESM and CommonJS consumers.

// CommonJS
const { createError, ServiceId } = require("error-definitions");

Dependency tracking

BMErrorResponse supports an optional dependency object to capture what dependency failed and the raw dependency error:

• name: e.g. Redis, Stripe, RabbitMQ
• type: INTERNAL | EXTERNAL
• original_message: raw message from the caught error

Which code should I use?

• INFRASTRUCTURE_FAILURE: internal tools/infrastructure dependencies (e.g. Redis, RabbitMQ)
• THIRD_PARTY_ERROR: external vendors/providers (e.g. Stripe)

Helper: handleDependencyError

Use handleDependencyError inside a try/catch to convert a raw dependency exception into a BMErrorResponse with the correct canonical code and populated dependency.original_message.

Example:

import { handleDependencyError, ServiceId } from "error-definitions";

try {
  await stripe.charges.create(...);
} catch (err) {
  return handleDependencyError(
    ServiceId.Payments,
    { name: "Stripe", type: "EXTERNAL" },
    err,
    { trace_id }
  );
}