Error Taxonomy

Conventional APIs classify failures in request processing: using HTTP status codes and error messages, they report whether a request was delivered, authenticated, authorized, structurally valid, and executed.

TCP/AP adds a deterministic interpretation layer. Before an Artifact is allowed to drive an action, the Kernel determines whether it resolves to exactly one admissible decision under the caller's declared Agentic Protocol, or does not. An output can be perfectly formed and still be refused here. That is why exactly one matters: an agent can only act on a single, unambiguous decision, so an ambiguous or unresolved artifact stops before it drives an action. That is what lets an autonomous caller route on failure without a human in the loop.

A conventional API tells it that a request failed. TCP/AP tells it which class of failure, who owns the remediation, whether a retry can change anything, and whether execution may continue. This page is the TCP/AP HTTP Standard for errors: the contract every conformant Kernel implements. Build your own against the rules below, or skip the build and adopt the Omnisensai Kernel, which implements the full standard with a complete remediation library out of the box.

Why TCP/AP is a distinct paradigm

Shifting from transport-layer status to decision-layer status.

TCP/AP HTTP Standard

The response envelope

Every response, success or failure, MUST use one envelope. This standard governs the status, verdict, and error members; provenance and attestation are specified by the provenance and conformance layers.

{
  "status": "EVALUATED" | "ERROR",
  "trace_id": "trace_20250128_a1b2c3d4e5f67890",
  "provenance": { /* input fingerprints, or null */ },
  "verdict": { /* result, or null */ },
  "error": { /* failure, or null */ },
  "attestation": { /* signed receipt, or null */ }
}

• status MUST be "EVALUATED" on a 200 or 422, and "ERROR" otherwise.
• trace_id MUST be present on every response: the opaque handle that correlates a decision across services and back to its audit record.
• verdict is { conformant, output_label } on an evaluated result, and null on an error. verdict.conformant is the execution gate.
• error is the error object (below) on every non-200, and null on a 200.

Failure domains

A conformant Kernel MUST attribute every non-conformant response to exactly one of the five failure domains below. The set is closed: a Kernel MUST NOT introduce a sixth domain. The domain identifies the layer in which remediation is required and maps to a primary remediation owner. A Kernel MUST assign the domain by the object that failed, not the stage that detected it: an artifact that arrives with the wrong type is an artifact failure even though request parsing is where it surfaces.

The domains trace the evaluation pipeline in order: request → protocol → artifact → interpretation → a conformant 200. interpretation is the one domain with shared ownership on purpose: a Kernel MUST NOT publish whether the drift came from the artifact or the protocol, because both present the same contract outcome (non-admissible). Every other domain has a single owner.

HTTP status codes

A conformant Kernel MUST use standard HTTP status codes to communicate each outcome: 2xx where the artifact conforms and is admissible for execution under the declared Agentic Protocol; 4xx where the request, protocol, or artifact is not admissible; 5xx for an unexpected service fault.

• It MUST return 200 only when the artifact resolves to exactly one admissible decision.
• It MUST return 422 for interpretation drift, and both underlying conditions MUST produce an identical response body: no cardinality, no per-rule detail.
• It MUST return 400 for request-, protocol-, and artifact-level structural failures, and 5xx for service faults.

The error object

On every non-200 response, the Kernel MUST include an error object answering four operational questions: which layer to remediate, what the specific condition is, whether a retry can change it, and what to do next.

{
  "failure_domain": "artifact",
  "failure_code":   "CONSTRAINTS_VALIDATION_FAILED",
  "param":          "/artifact/years_experience",
  "retryable":      false,
  "message":        "The artifact violates the declared constraints: expected integer, got string. Regenerate it to conform and resubmit."
}

The error object sits inside the response envelope defined above; only a 200 with verdict.conformant: true is admissible for execution.

Baseline failure codes

A conformant Kernel SHOULD emit these codes for the conditions shown, and MAY extend the set within a domain. Fixing a shared baseline is what lets a caller write portable failure handling across Kernels.

One code stays deliberately coarse. INTERPRETATION_DRIFT is the interpretation failure: a structurally valid artifact that the Agentic Protocol could not resolve to a single, actionable decision, so it is not safe to act on automatically. (An agent needs exactly one unambiguous decision; an ambiguous or unresolved artifact needs a human.) A conformant Kernel MUST keep the reason it failed to resolve out of the response; that detail belongs only in the protected audit record.

< 422 {
  "status": "EVALUATED",
  "verdict": { "conformant": false, "output_label": null },
  "error": {
    "failure_domain": "interpretation",
    "failure_code":   "INTERPRETATION_DRIFT",
    "param":          null,
    "retryable":      false,
    "message":        "The produced artifact was ambiguous or unresolved; no single interpretation to act on. Regenerate the artifact or revise the protocol before resubmitting."
  }
}

Error handling

These are the reciprocal obligations for a caller consuming a conformant Kernel. Route on the envelope faithfully and preserve the trace_id everywhere.

• A caller MUST treat 200 as the only admissible outcome and act on verdict.output_label; every other status MUST be routed as a failure, not acted on.
• A caller MUST route to the owner on failure_domain and branch on failure_code, never on message. Use param to locate the field.
• A caller MUST retry only when retryable is true, with exponential backoff. A 400 or 422 is deterministic and MUST NOT be retried unchanged (a 422 may still be resolved by regenerating the artifact or revising the protocol).
• A caller MUST NOT collapse a structured response into a generic error; it SHOULD surface the domain, code, and reason.

In a governed TCP/AP runtime these rules are not written as code. Routing lives in the Switchboard as data, keyed on the objective and its outcome; the Operator walks the table and branches nothing. Each failure domain routes to its owner's recovery objective, so the taxonomy is the routing.

// decisions live here, as data. The Operator walks it and branches nothing.
{
  // "objective | outcome"                          ->  next objective
  "screen_cv | CONFORMANT | QUALIFIED":        "start_interview",
  "screen_cv | CONFORMANT | NOT_QUALIFIED":    "send_rejection",
  "screen_cv | CONSTRAINTS_VALIDATION_FAILED": "reprompt_model",        // artifact
  "screen_cv | INTERPRETATION_DRIFT":          "human_review",          // interpretation
  "* | PROTOCOL_MALFORMED":                    "alert_protocol_author", // protocol
  "* | MISSING_FIELD":                         "alert_integrator",      // request
  "* | KERNEL_FAULT":                          "retry_backoff"          // platform
}

The Switchboard is a first-class TCP/AP concept with its own reference; the runnable switchboard and Operator templates live on GitHub. Integrating directly over HTTP instead? Apply the same rules imperatively: see the raw-client template in the Kernel API reference.