
Valid JSON, Wrong Decision: The AI Output Contract
A field guide to versioning, validating, repairing, and safely consuming structured AI output without confusing schema compliance with truth or authority.
Read MoreZharfAI Team

A customer-support assistant is serving short policy questions when an evaluation job submits thousands of long prompts. At the same time, one agent begins a document-heavy tool workflow, a provider slows down, and impatient clients retry. Every request is individually legitimate. Together they fill the queue, extend time to first token beyond the users’ deadlines, occupy memory with work that may never be consumed, and make the service spend its remaining capacity finishing obsolete attempts.
“Add more GPUs” is not a complete answer. Capacity can disappear faster than new instances warm, a downstream API can become the bottleneck, and a larger fleet still needs rules for scarcity. The operating decision is more precise: when capacity is constrained, which AI work should be admitted now, queued briefly, degraded safely, deferred durably, or rejected clearly?
This field guide develops an admission-control architecture for that decision. It treats the queue as a policy surface—not an accidental buffer—and optimizes for useful, on-time outcomes rather than raw request throughput.
Overload creates a feedback loop. Work takes longer, more requests remain in flight, clients reach their deadlines, retries add offered load, and the service completes responses nobody is waiting to use. Google’s SRE guidance on cascading failures recommends bounded queues, early load shedding, deadline propagation, and task-specific graceful degradation because queued and late work consumes resources without necessarily producing value.
Amazon’s current load-shedding guidance makes a useful distinction between throughput, all work offered to a service, and goodput, work completed successfully and soon enough for the client to use. An AI gateway can report rising requests per second while goodput falls: generations finish after disconnection, tool calls outlive approvals, and batch traffic delays urgent interactive work.
Autoscaling remains necessary, but it is not admission control. Scaling reacts to a signal and has a delay. Admission control decides what the system may accept at this instant, with the capacity and dependencies actually available. A resilient service needs both.
Several mechanisms are well established:
The Reactive Streams specification, for example, defines non-blocking backpressure so a subscriber controls demand and buffers can remain bounded. Kubernetes API Priority and Fairness classifies requests into priority levels, isolates concurrency, applies fair queuing and shuffle sharding, and can either queue briefly or reject excess traffic. Envoy’s overload manager turns monitored resource pressure into staged actions such as stopping new requests; its documentation distinguishes host overload protection from upstream circuit breaking.
The five-way disposition model in this article—admit, queue, degrade, defer, reject—is ZharfAI analysis built from those mechanisms. It is not a standard published by Google, Amazon, Kubernetes, Envoy, Reactive Streams, vLLM, or the IETF. The AI-specific work is to define request cost, consequence, fairness, and safe degradation without allowing the model to claim its own priority.
Do not let a raw prompt enter a shared inference queue. Build a trusted envelope outside the model:
| Field | Why the controller needs it |
|---|---|
| Logical intent and attempt ID | Distinguish one business request from retries |
| Authenticated tenant and actor | Enforce quotas and investigate abuse |
| Workload class | Separate interactive, action, control, and batch work |
| Absolute deadline | Avoid starting work that cannot finish usefully |
| Consequence and reversibility | Prevent unsafe degradation of high-impact work |
| Estimated cost | Budget prompt, output, retrieval, tools, and concurrency |
| Dependency set | Protect providers, vector stores, tools, and databases independently |
| Allowed degraded modes | Define cheaper behavior before an incident |
| Cancellation channel | Stop downstream work after disconnect or withdrawal |
| Budget owner and policy version | Make the decision accountable and reproducible |
The model may estimate complexity as one signal, but it must not set priority, tenant, deadline, approved, or emergency. Derive trusted values from authenticated product state, the requested operation, and versioned policy. This extends the AI permission layer: access authority and resource priority are different decisions, but neither belongs to generated prose.
Cost must be multi-dimensional. A 200-token classification and a 200-token answer with five retrieval calls do not consume the same resources. An agent may hold an inference slot while waiting for a tool, then create fresh inference and database work. Estimate at least prompt tokens, maximum output tokens, expected generation time, retrieval fan-out, tool calls, and retained state. Reconcile the estimate against actual use so bad forecasts do not become permanent policy.
Current vLLM production metrics expose running and waiting requests, queue time, prompt and generation tokens, prefill and decode time, and KV-cache use. These are implementation signals, not a complete business admission policy, but they show why request count alone cannot describe model-serving pressure.
| Disposition | Use when | Required response |
|---|---|---|
| Admit | Capacity, dependency, deadline, quota, and policy gates pass | Reserve budget and begin bounded work |
| Queue | A short burst is likely to clear before the deadline | Return position/state where appropriate; enforce age and size limits |
| Degrade | A prevalidated cheaper mode still satisfies the user’s decision | Name the reduced mode and preserve essential safeguards |
| Defer | Work is valuable but not time-sensitive | Persist intent durably, schedule it, and provide status/cancellation |
| Reject | The queue is full, deadline impossible, quota exhausted, or no safe mode exists | Fail early with a stable reason and retry semantics |
Do not hide rejection as a long spinner. RFC 6585 defines HTTP 429 for rate limiting and permits a Retry-After field; its specification deliberately leaves identification and counting policy to the server. Use 429 when a caller or quota is constrained, and choose other status semantics deliberately for service-wide unavailability. More important than the exact code is an honest reason: tenant_quota, class_capacity, dependency_open, deadline_impossible, or queue_full.
A retry time is a promise only if the server can justify it. When recovery is unknown, say so. Clients should not convert every rejection into synchronized retries. Carry the stable logical intent and retry budget described in the retry and idempotency field guide.
Queue capacity needs three bounds:
Check the absolute deadline when a request arrives, before every expensive stage, and again when it leaves a queue. Propagate the remaining deadline to retrieval, inference, and tools. Cancel on user disconnect where the product semantics allow it. A queue item without a live consumer, durable business purpose, or authoritative status route is usually waste.
FIFO is not automatically fair. A long document job at the head can block many short lookups; one tenant can fill every slot; repeated attempts can appear as independent demand. Classify by workload and then isolate flows within a class. The goal is not to make every request equally fast. It is to prevent one source or cost shape from removing everyone else’s chance of progress.
Kubernetes APF offers a useful analogy: requests can occupy different numbers of “seats,” priority levels have isolated concurrency, and fair queuing reduces starvation among flows. Copy the principle, not the configuration. AI cost estimates are uncertain and change with context length, cache state, model, batching, and tool behavior.
Amazon’s multi-tenant fairness guidance combines per-workload quotas, throttling, and isolation so an unplanned increase from one tenant does not spread failure across all tenants. A practical AI policy can combine:
Avoid an unlimited “highest priority” lane. If every team can mark work urgent, priority becomes an attack on fairness. Require a controlled vocabulary, authenticated eligibility, a maximum share, and review of who used the override. Consequential writes are not necessarily the highest-throughput priority; sometimes the correct overload behavior is to stop new writes while preserving read-only diagnosis and cancellation.
Measure fairness at the outcome, not only the admission gate. Track whether tenants and workload classes receive their intended share of useful completions, whether low-volume flows make progress, and whether cost-estimation error systematically harms one language, document type, or customer segment.
Graceful degradation must be defined per task before overload:
Do not degrade by dropping authorization, evidence, output validation, tenant isolation, or post-action verification. Do not silently use stale context, broaden a cache key, remove citations, or substitute a model that has not passed the workload’s gate. The model-routing guide explains why provider health and cost are only part of a routing decision; an overload fallback still needs capability and policy compatibility.
Treat every degraded mode as a separate product behavior with its own evaluation, user message, metrics, and rollback. Exercise it regularly. A rarely used emergency path is likely to be the least reliable code in the service.
Consider an illustrative bilingual operations platform with a measured stable capacity of 40 interactive-equivalent seats. A short policy lookup costs one seat, a long-document synthesis three, and a tool-using work-order proposal four plus a separate tool budget. These numbers are local measurements, not universal ratios.
The controller reserves two seats for health, cancellation, and incident operations. It assigns 18 to interactive lookup, eight to work-order proposals, and 12 to batch evaluation. Unused batch seats may be borrowed, but the batch class cannot consume the interactive floor. Each tenant receives a bounded share inside each class, and requests carry absolute deadlines.
A provider slowdown doubles generation time while one tenant submits 500 evaluation cases. The controller:
The service completes fewer total requests per minute, but more users receive useful on-time outcomes. That is the point. After recovery, batch capacity drains gradually so it does not create a second spike.
Capacity tests should increase offered load beyond the point where useful throughput plateaus. Include:
Verify that goodput plateaus rather than collapses, protected classes still progress, expired work is not executed, rejections are cheap, cancellations propagate, and degraded modes remain semantically safe. Connect the results to the operational readiness checklist, including named owners and a tested return to normal mode.
The AI observability guide covers trace linkage across models and tools. Add admission-specific measures:
Revisit policy when the request mix changes, a new model changes cost shape, context limits expand, tools are added, tenant size becomes more uneven, a degraded mode fails evaluation, or operators repeatedly use the emergency lane. Do not tune only to reduce rejection rate. A lower rejection rate can mean the system is accepting work it cannot finish.
Before a shared AI service accepts production traffic, answer yes:
The queue determines who waits, who succeeds, whose deadline expires, and which work consumes the last healthy unit of capacity. That makes it a product, reliability, and governance policy. Design it explicitly before overload designs it for you.
Retry-After semantics.
A field guide to versioning, validating, repairing, and safely consuming structured AI output without confusing schema compliance with truth or authority.
Read More
An operating guide for deciding when an AI call may be retried, hedged, failed over, or reconciled—and for preventing timeout ambiguity from becoming duplicate business action.
Read More
A practical architecture for deciding when an AI answer may be reused, which context must enter the cache key, and when freshness, authority, or consequence requires a new result.
Read MoreIf this note maps to a real system in your organization, start with the services page or a shipped case study.