DEV Community

Cover image for FullAgenticStack WhatsApp-first: RFC-WF-0036
suissAI
suissAI

Posted on

FullAgenticStack WhatsApp-first: RFC-WF-0036

#webdev #programming #rfc #opensource

RFC-WF-0036

Error Taxonomy & Reason Codes (ETRC)

Status: Draft Standard
Version: 1.0.0
Date: 20 Nov 2025
Category: Standards Track
Author: FullAgenticStack Initiative
Dependencies: RFC-WF-0003 (CCP), RFC-WF-0004 (ACSM), RFC-WF-0006 (EAS), RFC-WF-0007 (OoC), RFC-WF-0008 (RCP), RFC-WF-0010 (IDS), RFC-WF-0018 (SMCL), RFC-WF-0020 (RAOS), RFC-WF-0030 (EQRP), RFC-WF-0021 (SECR)
License: Open Specification (Public, Royalty-Free)

Abstract

This document specifies Error Taxonomy & Reason Codes (ETRC) for WhatsApp-first systems. ETRC defines a canonical taxonomy of error categories and stable reason codes for command rejection, execution failures, policy blocks, idempotency conflicts, recovery outcomes, and abuse controls. ETRC enables consistent conversational explanations (OoC), deterministic audit reporting (CATS/RCMC), and interoperable evidence records (EAS) across implementations.

Index Terms— error taxonomy, reason codes, failure modes, observability, audit reporting, interoperability.

I. Introduction

Without standardized reason codes, systems devolve into “string errors” that are impossible to aggregate, audit, or explain safely. WhatsApp-first systems require:

  • concise explanations in chat (OoC)
  • precise machine-readable reasons in evidence (EAS)
  • consistent remediation guidance in audits (CATS)

ETRC standardizes the reason codes and their semantics.

II. Scope

ETRC specifies:

  • Error categories and reason code format
  • Minimum reason code catalog for WFS v1.0
  • Mapping of lifecycle stages to reason code locations
  • Requirements for OoC explanations using codes
  • Requirements for evidence recording of codes
  • Extension rules for domain-specific codes (SECR)

ETRC does not mandate logging frameworks; it defines standardized codes.

III. Normative Language

MUST, MUST NOT, SHOULD, SHOULD NOT, MAY are normative.

IV. Definitions

Reason Code: A stable machine-readable identifier describing why something failed/was denied/was blocked.
Category: A high-level grouping of reason codes.
User Message: A safe, redacted explanation suitable for conversational output.
Operator Detail: A more detailed explanation available only to privileged operators (redacted).

V. Reason Code Format (Normative)

Reason codes MUST use the format:

WFS.<CATEGORY>.<CODE>

Where:

  • CATEGORY is uppercase alphanumeric with underscores
  • CODE is uppercase alphanumeric with underscores

Examples:

  • WFS.AUTHZ.DENIED_SCOPE
  • WFS.CONFIRM.EXPIRED
  • WFS.IDEM.CONFLICT
  • WFS.EXEC.EXTERNAL_PROVIDER_FAILED

VI. Where Reason Codes Appear (Normative)

Reason codes MUST be recorded in at least:

  • EAS security.authz.reason_code (authorization/policy denials)
  • EAS payload.result.error.code (execution failures)
  • EAS lifecycle rejection/failure artifacts (execution.rejected, execution.failed)
  • OoC responses (mapped to safe human explanations)
  • EQRP error responses (where applicable)

VII. Minimum Reason Code Catalog (v1.0.0)

A. Input & Parsing (WFS.INPUT.*)

  • WFS.INPUT.UNSUPPORTED_TYPE — unsupported message type
  • WFS.INPUT.MALFORMED — malformed payload
  • WFS.INPUT.STT_FAILED — STT processing failed
  • WFS.INPUT.AMBIGUOUS_INTENT — intent cannot be resolved
  • WFS.INPUT.AMBIGUOUS_TARGET — target cannot be resolved
  • WFS.INPUT.MISSING_REQUIRED_ARG — missing required argument
  • WFS.INPUT.INVALID_ARG — argument invalid format/value

B. Canonicalization & Registry (WFS.REG.*)

  • WFS.REG.UNKNOWN_COMMAND — command not in CRCD
  • WFS.REG.SCHEMA_VALIDATION_FAILED — args schema invalid
  • WFS.REG.DEPRECATED_COMMAND — command deprecated (still accepted per policy)
  • WFS.REG.MISCONFIGURED_POLICY_BINDING — missing required policy id

C. Confirmation & Approval (WFS.CONFIRM.* / WFS.APPROVAL.*)

  • WFS.CONFIRM.REQUIRED — confirmation not provided
  • WFS.CONFIRM.STRENGTH_REQUIRED — destructive requires strengthened confirmation
  • WFS.CONFIRM.INVALID_TOKEN — token/phrase mismatch
  • WFS.CONFIRM.EXPIRED — confirmation expired
  • WFS.APPROVAL.REQUIRED — approval required
  • WFS.APPROVAL.DENIED — approval denied
  • WFS.APPROVAL.EXPIRED — approval expired

D. Authorization & Step-up (WFS.AUTHZ.* / WFS.STEPUP.*)

  • WFS.AUTHZ.DENIED_SCOPE — missing scope
  • WFS.AUTHZ.DENIED_POLICY — policy forbids action
  • WFS.AUTHZ.DENIED_TENANT — tenant boundary violation
  • WFS.STEPUP.REQUIRED — step-up required
  • WFS.STEPUP.FAILED — step-up failed
  • WFS.STEPUP.EXPIRED — step-up freshness expired

E. Idempotency & Delivery (WFS.IDEM.*)

  • WFS.IDEM.DUPLICATE_REPLAYED — duplicate detected; outcome replayed
  • WFS.IDEM.IN_PROGRESS — original in progress; duplicate suppressed
  • WFS.IDEM.CONFLICT — idempotency collision (different envelope, same key)
  • WFS.IDEM.STORE_UNAVAILABLE — dedupe store failure (fail closed for mutation)

F. Execution (WFS.EXEC.*)

  • WFS.EXEC.STARTED — informational (optional)
  • WFS.EXEC.FAILED — generic execution failure
  • WFS.EXEC.TIMEOUT — execution timed out
  • WFS.EXEC.EXTERNAL_PROVIDER_FAILED — connector/provider failure
  • WFS.EXEC.EXTERNAL_PROVIDER_REJECTED — provider rejected request
  • WFS.EXEC.PARTIAL_EFFECTS — partial effects applied (requires recovery guidance)
  • WFS.EXEC.NOT_RETRYABLE — failure is non-retryable

G. Recovery & Compensation (WFS.RCP.*)

  • WFS.RCP.NOT_AVAILABLE — no recovery actions available
  • WFS.RCP.RETRY_LIMIT_REACHED — retry cap reached
  • WFS.RCP.REPROCESS_UNSUPPORTED — no checkpoints
  • WFS.RCP.COMPENSATION_REQUIRED — compensation needed for convergence
  • WFS.RCP.COMPENSATION_FAILED — compensation failed
  • WFS.RCP.BLOCKED_NEEDS_OPERATOR — requires operator action/approval

H. Observability & Evidence (WFS.OOC.* / WFS.EAS.*)

  • WFS.OOC.FORBIDDEN_DETAIL — caller not allowed detail level
  • WFS.EAS.NOT_FOUND — evidence not found (policy-defined)
  • WFS.EAS.REDACTED — content redacted per policy
  • WFS.EAS.INTEGRITY_MISMATCH — hash/signature mismatch

I. Abuse Controls (WFS.ABUSE.*)

  • WFS.ABUSE.RATE_LIMITED — throttled
  • WFS.ABUSE.TOKEN_BRUTEFORCE — too many token attempts
  • WFS.ABUSE.SUSPICIOUS_PATTERN — flagged behavior
  • WFS.ABUSE.LOCKDOWN_ACTIVE — restricted by lockdown mode

VIII. OoC Explanation Requirements (Normative)

OoC MUST map reason codes to safe, human-readable explanations:

  • user-level: minimal, redacted, actionable
  • operator-level (privileged): may include additional context and suggested remediation

OoC MUST NOT leak sensitive details (scopes lists, internal topology, secrets) to non-privileged users.

IX. Evidence Requirements (Normative)

For any execution.rejected or execution.failed artifact, evidence MUST include:

  • reason_code
  • reason_human (optional but recommended; redacted)
  • whether retryable (payload.result.error.retryable)
  • pointers to recovery options when applicable (RCP)

X. Extension Rules (SECR)

Implementations MAY define domain-specific codes, but MUST:

  • prefix with WFS.DOMAIN.<DOMAIN_NAME>.* or WFS.EXT.<ORG>.*
  • document semantics
  • avoid changing meaning of existing codes
  • include mapping to OoC explanations

XI. Conformance Requirements

An implementation is ETRC-compliant if it:

  1. uses standardized reason code format
  2. records reason codes in evidence for rejections/failures
  3. maps codes to safe OoC explanations
  4. uses consistent codes across EQRP and audit outputs
  5. supports extensions without breaking consumers

XII. Relationship to Other RFCs

  • CCP (0003): confirmation and canonicalization errors
  • ACSM (0004): authz/step-up denials
  • EAS (0006): evidence recording locations
  • OoC (0007): conversational explanation mapping
  • RCP (0008): recovery outcome codes
  • IDS (0010): idempotency codes and fail-closed behavior
  • SMCL (0018): lifecycle stage alignment
  • RAOS (0020): rate limiting and lockdown codes
  • EQRP (0030): query error codes
  • SECR (0021): extension rules

XIII. Security Considerations

Reason codes can become an oracle for attackers if too specific. ETRC requires safe user-level explanations and scope-gated operator detail. Evidence stores should retain precise codes for audit while conversational outputs remain redacted.

XIV. Conclusion

ETRC turns errors into a standardized language across chat, evidence, audits, and tooling. By defining stable reason codes with safe explanation mappings and extension rules, WhatsApp-first systems become easier to operate, debug, certify, and evolve—without leaking sensitive internals.

References

[1] RFC-WF-0003, Conversational Command Protocol (CCP).
[2] RFC-WF-0004, Administrative Command Security Model (ACSM).
[3] RFC-WF-0006, Evidence Artifact Schema (EAS).
[4] RFC-WF-0007, Observability over Conversation (OoC).
[5] RFC-WF-0008, Recovery & Compensation Protocol (RCP).
[6] RFC-WF-0010, Idempotency & Delivery Semantics (IDS).
[7] RFC-WF-0018, State Model & Command Lifecycle (SMCL).
[8] RFC-WF-0020, Rate Limits, Abuse Controls & Operational Safety (RAOS).
[9] RFC-WF-0030, Evidence Query & Retrieval Protocol (EQRP).
[10] RFC-WF-0021, Schema Extensions & Compatibility Rules (SECR).

Concepts and Technologies

Reason code catalogs, structured error taxonomies, safe conversational explanations, audit-friendly failures, idempotency conflict signaling, recovery outcome coding, rate limit signaling, redaction-aware error surfaces, extensible domain-specific error namespaces.

Top comments (0)