Failure reasons

The one error type DomainKit raises, the sixteen reasons it carries, the HTTP status each answers with, and what a host should do about each of them.

Every DomainKit operation fails with one DomainKit.Error. It carries exactly one Reason, and category, isRetryable, and httpStatus all derive from that reason. Hosts match on the reason; nothing parses a message.

import { DomainKit, Reason } from "domainkit";

The reasons

Categories

category groups the reasons for logging and metrics: request, auth, plan, provider, storage, internal.

Matching

/** Every failure is one `DomainKit.Error`; the reason says what to do next. */
export const explain = applyAndSummarise.pipe(
  Effect.catchTag("DomainKitError", (error) =>
    Match.value(error.reason).pipe(
      Match.tag("Conflict", ({ operations }) =>
        Effect.succeed(`Fix ${operations.length} conflicting record(s) first`),
      ),
      Match.tag("Stale", () => Effect.succeed("The zone moved; build a new plan")),
      Match.tag("Expired", () => Effect.succeed("The plan aged out; build a new one")),
      Match.orElse(() => Effect.succeed(error.message)),
    ),
  ),
);

DomainKit.isError(value) narrows an unknown to the error, for a catch at a foreign boundary.

Over the wire

domainkit/server answers with the error value itself at the status its reason derives, so a Conflict is a 409 whose body still carries the conflicting operations and a Reconnect is a 403 naming the connection. domainkit/client decodes that body back into the same DomainKit.Error, reason intact.

A reply the client cannot read as one came from in front of the server: a proxy, a login page, a maintenance window. Those are classified from the status instead, and always name the transport’s base URL as the origin. The transport carries that table.

In the UI

@domainkit/react renders a sentence per reason from Messages.Catalog, so nothing shows a tag. Override one key to change one sentence.

/** A failure keeps the `DomainKit.Error`, so read `reason`, `category`, and `isRetryable`. */
export function ConnectionProblem({ domain }: { readonly domain: string }) {
  const { messages } = DomainKit.useDomainKit();
  const connection = Connect.useController({ domain });
  const state = connection.state;
  if (state._tag !== "Failure") return null;
  return (
    <p role="alert">
      {Messages.failure(state.error, messages)}
      {state.error.isRetryable ? (
        <button onClick={connection.retry} type="button">
          Try again
        </button>
      ) : null}
    </p>
  );
}

Troubleshooting covers what to do when one of these keeps happening.