The Envelope's Version Field: Adding a Class Safely

Here is a working schema. It is deliberately loose on class and tight on everything else.

{
  "version": "1.3",
  "class": "rate_limited",
  "code": "upstream_429",
  "message": "Upstream model provider returned 429; retry after 2s.",
  "retryable": true,
  "details": {
    "retry_after_ms": 2000,
    "provider": "example",
    "legacy_class": "throttled"
  }
}

The key decision is that class is an open string, not a closed enum. Closed enums are the classic compatibility trap: removing or adding a symbol has subtle effects that even schema registries have historically mis-handled as discussed for Avro enums. If you model class as an enum in a generated client, a new server value deserializes to a null or throws. Open string plus a documented known-values list plus a default is strictly safer.

The second decision is retryable. Split recovery responsibility explicitly: the orchestration layer owns transient retries, the model owns reasoning-based recovery when the payload is wrong per this error-handling guide. A boolean on the envelope makes that split mechanical. Do not make consumers infer retryability from class, because you will want to change one class's retryability without changing the class name.

Write the rules down and enforce them in CI. The standard vocabulary is worth reusing: a backward-compatible change lets new readers read old data, a forward-compatible change lets old readers read new data, and full compatibility means both as Confluent defines the terms.

For an error envelope you want forward and backward compatibility at once, because producers and consumers roll out independently. Additive changes to an open JSON schema with additionalProperties allowed achieve that per this analysis of JSON Schema evolution. This table is the decision rule to paste into your contributing guide.

Two details are easy to get wrong. First, always upgrade consumers before producers for backward-compatible changes, which is the standard operational rule for backward compatibility described in this guide. Second, treat unknown details keys as ignorable, but never treat an unknown top-level field as an error; a lenient reader is what makes additive changes safe.

Set retryability at the boundary. Do not let consumers throw on an unknown class.

KNOWN_CLASSES = {"auth", "invalid_input", "rate_limited", "upstream", "not_found", "unknown"}

def normalize(envelope: dict, source: str) -> dict:
    v = envelope.get("version", "1.0")
    cls = envelope.get("class")
    if not isinstance(cls, str) or cls not in KNOWN_CLASSES:
        metrics.increment("envelope.unknown_class", tags={"source": source, "class": str(cls)})
        cls = "unknown"
    return {
        "version": v,
        "class": cls,
        "raw_class": envelope.get("class"),
        "retryable": bool(envelope.get("retryable", False)),
        "message": envelope.get("message", ""),
        "details": envelope.get("details") or {},
    }

The fallback rule the consumer needs is simple and worth stating verbatim in your docs: if you see a class you do not know, treat it as unknown, honor retryable, and do not retry a non-retryable unknown error. That last clause matters. 400 and 422 are not retryable while 429 and 503 are, and a client that cannot tell them apart either retries forever or gives up on transient failures per this status code decision guide. Your envelope should encode that distinction in the boolean, so unknown plus retryable: false is safe by construction.

For agents specifically, an unknown class should route to replan rather than retry. Persistent semantic errors, 409 conflicts and 422 rejections among them, will not clear on a backoff, and retrying them burns latency budget and can double-charge on non-idempotent tools argued in detail here. Counting fallbacks per source is how you find the one orchestrator that never got the message.

Order matters more than any single step. This sequence has four phases and a gate between each.

1. Teach consumers first. Ship the open-string parsing, the default class, and the fallback metric to every consumer you control. Update the system prompt for LLM-based consumers too: production prompts are modular, versionable artifacts and output-format sections must state the unknown-class rule explicitly per these design patterns. If agents read the envelope, the instruction "if the class is not in this list, treat it as unknown and check retryable" belongs in the prompt, not in a wiki.
2. Emit both classes, behind a flag. The producer writes the new class and the old name in details.legacy_class, and keeps the old top-level value for any consumer pinned to it. Gate the new emission with a feature flag so you can roll back without a deploy.
3. Watch the fallback counters. Hold the flag on until fallback hits for the new class are zero, or stable and explained, for longer than your longest deploy and cache TTL. If an external consumer cannot ship in that window, stop and extend. Publish the class list so consumers can diff it.
4. Flip the default and retire. Turn the flag off for the old emission, keep the old class in the known list for one more window, then remove it in a major bump. Announce before each step.

Fault injection belongs in phase 1. You cannot trust an error path you have never exercised. Fault-injection frameworks exist precisely to test how agents respond to malformed inputs and tool failures, and the evidence they produce is subtler than it looks: in one study, among 44 runs where counterevidence eventually became visible, only 17 received it before the faulty fact was first used SSCBench. Translate that to your tests: inject the new class in a run where the consumer must act on it before any fallback path has been exercised, and check the fallback actually fires.

A dependable injection proxy makes this a test suite rather than a manual drill the Agent Error Simulator. If tool errors are handled at the wrong layer, agents degrade silently as this retry guide warns.

You need three signals, and only one of them should page anyone.

Watch for the silent version of this problem as well. A consumer that falls back to unknown and then treats unknown as "retry" will look healthy in your dashboards while quietly retrying work that can never succeed. Datadog data cited in that failure analysis puts one in twenty AI model requests failing in production while systems keep returning outputs that appear correct source. Fallback hits are the one early warning you get.

If you would rather not hand-roll compatibility tests and fallback metrics per provider, one API for text, image, video, audio and embedding models keeps the envelope shape consistent across providers: Quanta Inference is OpenAI-compatible and prepaid, which removes one class of variance (provider-specific error shapes) before you even version your own.