Errors and refusals

Overview

Callers meet three kinds of “no”. A rule refusal means a rung of the Right Path, or a named person, said no. A platform refusal means something on our side failed, so nothing was allowed. A contract error means the request itself did not meet the contract and never reached the Right Path. Each has a different envelope, a different effect on the chain and the meter, and a different right response.

Three kinds of no

The refusal envelope

A refusal comes back in the same envelope as every other outcome, with a refusal block added. The block is built for two readers: your code, which branches on class, and a person, who reads the plain words.

HTTP/1.1 200 OK

{
  "outcome": "refused",
  "rung": 3,
  "write_id": "wr_specimen_7c3",
  "refusal": {
    "code": "G4_GST_RATE_MISMATCH",
    "class": "rule",
    "reason": "The invoice charges 12% GST; the rate table says 18% for HSN 8483.",
    "remedy": "Correct the rate on the invoice, or update the rate table under dual control.",
    "contact": "usr_specimen_controller"
  },
  "record": { "id": "00000000-0000-0000-0000-000000000000", "version": 0 },
  "proof": { "seal": "elan1.proof.seal.v6", "seq": 1043, "digest": "sha256:4be190c7…" },
  "meter": { "governed_actions": 0.4, "inr": 0.64 }
}

# Metered at 0.4 of a governed action: ₹0.64 at L1, beyond the allowance.

HTTP/1.1 503 Service Unavailable

{
  "outcome": "refused",
  "write_id": "wr_specimen_7c4",
  "refusal": {
    "code": "<platform code from the frozen register>",
    "class": "platform",
    "reason": "A dependency of the gate check did not answer. Nothing was allowed."
  },
  "meter": { "governed_actions": 0, "inr": 0 }
}

# Ours, not a rule. Never billed. Never an allow.

Field names are illustrative; the exact names are in the KernelPort v1 reference. Conformance test C8 checks the shape: a register code, the rung, a zeroed record_id, record_version 0 and a meter quantity of 0.4.

Refusal codes

Every refusal code comes from one closed register. A code that is not in the register cannot be emitted, so a caller can always tell a known refusal from anything else. The register, its codes and the rung each code belongs to are part of KernelPort v1 and are shared with customers; this site uses a handful of illustrative codes, always marked so.

Rules for callers

• Treat a code as an opaque, case-sensitive string. The two styles above — underscored and dotted — are both illustrative; do not depend on either.
• Branch on outcome and refusal.class. Use the code for display, logging and support, not for control flow you cannot change later.
• Never invent a code, and never map an unknown code to an allow. An unknown code is still a refusal.

Where refusals come from

Any rung can refuse. The rung tells a person where to look; the code tells them exactly what failed.

Rungs 8 PROOF and 9 METERED do not refuse a write on its merits. If the chain writer cannot seal, nothing is allowed and the intent ends as a platform refusal. Rungs 3 to 8 cannot reach a model client: a model may produce a write intent, never an allow or a refusal reason.

Handling each case

A handler, end to end

The same logic as code. It persists the write_id before sending, retries only with the same write_id, fails closed on silence, and writes only on committed.

// Illustrative. Exact field names are in the KernelPort v1 reference.
type Outcome = "committed" | "refused" | "escalated";

async function propose(intent: WriteIntent): Promise<void> {
  await store.saveIntent(intent);                       // persist write_id first

  let res: Response;
  try {
    res = await sendWithRetry(intent);                  // same write_id on every retry
  } catch {
    return hold(intent, "elan1 did not answer. Nothing was written.");   // fail closed
  }

  if (res.status >= 400 && res.status < 500) {
    const { error } = await res.json();
    return fixRequest(intent, error);                   // contract error: no record exists
  }

  const body = await res.json();
  switch (body.outcome as Outcome) {
    case "committed":
      await writer.apply(intent, body.proof);           // Mode B: your system writes now
      return;
    case "escalated":
      return waitFor(body.obligation);                  // webhook resolves it; expiry is a refusal
    case "refused":
      if (body.refusal.class === "platform") {
        return hold(intent, body.refusal.reason);       // ours; never billed; try later as a new intent
      }
      return showRefusal(intent, body.refusal, body.rung); // a rule or a person said no; 0.4 of a governed action
  }
}

HTTP/1.1 400 Bad Request

{
  "error": {
    "class": "contract",
    "reason": "write_type 'journal_entry.repost' is not a write type this API knows.",
    "field": "write_type"
  }
}

# The request never reached the Right Path. No record.

Showing a refusal to a person

A refusal is only useful if the person who must act on it can read it. elan1 Work’s refusal card is the pattern to follow: a typed code in plain words, what to fix, and who to ask.

Heading

REFUSED, never an error colour alone: always the word.

Code

The typed code in a monospace face, exactly as received.

Where

The rung where it stopped, for example 3 PRE-GATES.

Why

refusal.reason in plain words.

Next

refusal.remedy and refusal.contact.

Evidence

“Recorded · 0.4 governed action”, with the proof sequence so anyone can find the record.

Testing your handling

Four conformance tests from the C1–C14 suite exercise exactly this behaviour. A third-party agent makes no claim to run on elan1 Govern until all fourteen pass.

See Conformance for the whole suite and how to run it.

What the customer reference covers

• The refusal register: every code, its class and its rung. Codes on this site are illustrative.
• The names of the refusal fields, including remedy and contact.
• The exact HTTP status codes for contract errors and platform refusals.
• How a reused write_id with a different payload is answered. Design as if it is refused.

These are fixed in KernelPort v1 and the record shape, and are listed in the full reference customers receive with their workspace.

Related pages