@iqx-limited/web-errors

The shared error contract between iqxWebHub, the iqxWEBv2 server and the iqxWEBv2 client:

• the error-code table (AUTH-SSO-004 → HTTP status + public message),
• the AppError class both servers throw,
• the response body shape and header names,
• parseErrorResponse ( ) so every client reads errors the same way, and
• the request-reference format shown to users next to the code.

Nothing in this package is secret — it is bundled into the browser. What a code means internally and what to check when it is reported lives on the IQX wiki page "Web error codes", keyed by code.

Install

npm i @iqx-limited/web-errors

ESM first (all three consumers are ESM), with a CommonJS build under dist/cjs for tooling that resolves require — Jest in the iqxWEB client needs it. Node ≥ 20.

Server usage (Fastify)

import { AppError, ERROR_CODE_HEADER, REQUEST_ID_HEADER } from "@iqx-limited/web-errors"

// Where the cause is known:
throw new AppError ( "AUTH-SSO-004", {
  detail: upstream.error_description,   // sanitised; only sent on debug-enabled requests
  cause: err,                            // for logs / Sentry, never sent
  attributes: { provider: "google" }     // for the log line, never sent
} )

// In the error handler:
const e = AppError.isAppError ( error ) ? error : new AppError ( "SYS-500", { cause: error } )
reply
  .code ( e.status )
  .header ( REQUEST_ID_HEADER, req.id )
  .header ( ERROR_CODE_HEADER, e.code )
  .send ( e.toBody ( req.id, req.debugEnabled ) )

Client usage

import { parseErrorResponse, formatErrorReference } from "@iqx-limited/web-errors"

const parsed = parseErrorResponse ( res.status, res.headers, res.error )
toastr.error ( parsed.message, undefined, { subtitle: formatErrorReference ( parsed ) } )
// → "We could not complete sign-in with the provider. Please try again."
//   "AUTH-SSO-004 · ref 7F3K2QX9BD"

parseErrorResponse never throws and understands the legacy bodies too (plain strings, { IQXFailure }, { IQXResult.IQXFailure.attrs.message }), falling back to the headers and then to a status-derived SYS-* code, so it can be adopted on the client before the servers are converted.

Response contract

Every error response carries the headers x-request-id and x-iqx-error-code. Once a server is on this package its body is:

{ "error": { "code": "AUTH-SSO-004", "message": "…", "ref": "7F3K2QX9BD", "detail": "…" } }

detail is only present on debug-enabled requests (server LOG_LEVEL=debug or the user listed in DEBUG_USERS). Such responses also carry x-iqx-debug: 1.

Adding a code

1. Add it to src/codes.ts under its area. Never renumber or reuse a code; mark retired ones deprecated: true.
2. Add the internal meaning and what-to-check to the wiki page.
3. npm test (format, status range, message hygiene, deliberate-sharing list).
4. Bump version in package.json, commit, tag vX.Y.Z, push the tag — the publish workflow does the rest.

Development

npm ci
npm test
npm run build

Publishing needs the NPM_TOKEN repository secret (the @iqx-limited scoped token).