eduKate Singapore

VIEW THIS AS

Auto mode follows the Route Engine until you choose a viewpoint.

YOU ARE HERE

ROUTE CHECK

CONNECTED TO

WHAT NEXT

Use the canonical route for this room, or HELP if you are unsure.

Next useful routeCanonical hubHELP

How Superintelligence Works | Agent HTTP Prefer Header — Async Work, Wait Budgets and Safe Response Choices

—

by

eduKate Asia
Three learners review open books together at a classroom table, with stacks of textbooks, stationery and a whiteboard in the bright room.

An AI agent that calls an HTTP API often has a choice about how much work to ask a server to do before it answers, and how much information to receive when that work succeeds. The HTTP Prefer request header lets a client express those choices without pretending it controls the server. A request might say Prefer: respond-async, wait=5, meaning that asynchronous handling is acceptable and that roughly five seconds of server-side processing is the preferred synchronous wait. Another might say Prefer: return=representation to request the updated resource instead of a minimal acknowledgement. The server may honor a preference, decline it, or support only part of it.

For agent engineering, the immediate practical lesson is to distinguish a preference from a guarantee. An HTTP 202 response is not proof that a task finished. A 204 response is not a resource representation. A short wait preference is not a hard end-to-end deadline. Robust agents make these distinctions explicit in their state machines, confirmation checks, retry behavior, and security boundaries. RFC 7240 defines Prefer and Preference-Applied. RFC 9110 defines modern HTTP semantics. The examples below are teaching calculations, not claims about observed performance or an existing superintelligent system.

Contents

The coordination problem: one request, several legitimate responses

Imagine an agent updating a calendar event on behalf of a user. After the write, one API might return the complete normalized event: server-assigned identifier, time zone, recurrence information and a fresh version tag. Another might return only a success code. Either could be valid for its API contract, but the first saves the agent a follow-up read while the second reduces response bytes. A client can express which outcome suits it by sending a preference. Neither choice changes the need to verify that the desired state was actually committed.

Now imagine an agent submitting a report-generation job that can take seconds or minutes. Keeping one HTTP connection open until completion risks request timeouts and awkward retries. An asynchronous design can acknowledge acceptance promptly and provide a status resource or task identifier. The Prefer mechanism permits a client to say it can handle this shape. The server still defines its own queueing, status endpoint, authentication, and completion semantics. The distinction is critical because client requests do not magically create a standard job protocol.

In this article, the term agent means ordinary present-day software using model-assisted planning and API calls. It does not imply that artificial superintelligence currently exists. The same protocol design applies to a script, a browser application, a batch job, or a human-operated integration; agent-specific risk arises because software can chain many calls before anyone notices one mistaken assumption.

A Prefer token is advisory, not a service-level agreement

RFC 7240 defines a way to express client preferences for optional server processing. A preference may change response timing, response size, validation leniency, or another documented server choice. It must not silently override mandatory protocol requirements, access control or the business operation itself. A client that requires a particular behavior for correctness needs a documented API guarantee, a negotiation mechanism with enforceable failure, or explicit response validation; the mere presence of a Prefer header is not enough.

An agent must therefore read the response it received, not the response it hoped to receive. If the server answers 200 with a representation despite return=minimal, the agent should parse the representation only according to its normal schema. If the server answers synchronously despite respond-async, the agent should recognize genuine completion according to the operation contract. If the server acknowledges asynchronous work, the agent should enter a pending state even if the request asked for immediate completion.

This is also why the header should not be used as a substitute for authorization, data ownership, idempotency keys, deadlines, or preconditions. Those controls have different responsibilities. Prefer answers a narrow question: which optional behavior does the client prefer? Safety is a separate layer and cannot be delegated to a preference token.

The wire format: tokens, values and parameters

A Prefer field is a comma-separated collection of preference tokens. Examples include Prefer: respond-async, wait=5 and Prefer: return=representation. Some tokens have values and some can have parameters. The field may appear as multiple header lines or one combined header line, subject to normal HTTP field handling. Token spelling is case-insensitive for comparison where the RFC says so; an implementation should parse according to the actual grammar rather than by fragile string searches.

The standard asks clients not to repeat the same preference token. When duplicates occur, the first instance controls and later instances should be ignored. That creates an important test case for proxies or libraries that merge header lines: the order of duplicate tokens can matter. A parser should not invent a value by taking the last occurrence, and an agent should not assume the two copies mean that the preference is more strongly desired.

Keep a typed distinction between recognized tokens and unrecognized extensions. An unrecognized preference must not be transformed into a command. An extension token may be meaningful to a particular service, but only that service’s documented contract can establish its semantics. Treat unexpected tokens and malformed values as a reason for careful parsing, not as free instructions supplied by a remote party.

Respond-async: permission to acknowledge work before it finishes

The respond-async preference tells a server that the client can handle an asynchronous response. A common pattern is an HTTP 202 Accepted response with a Location header pointing to a server-defined resource associated with the task. RFC 7240 gives this as an example, not as a universal requirement or a complete polling specification. A compliant implementation can choose a different mechanism, or ignore the preference entirely.

The useful distinction is between admission and completion. Consider a document-conversion API. A 202 response may mean the server accepted the request for processing. It does not establish that a converted file exists, that the transformation passed validation, or that the resulting file is authorized for distribution. The client should record a pending operation, obtain or securely store the server’s task reference, and consult the API’s documented completion mechanism before making any final claim.

An agent that interprets 202 as success at the business level can cause cascading damage: a subsequent email announces an attachment that has not been produced; a database row claims a backup exists; or a second agent marks a release as deployed. Separate the HTTP transaction result from the task lifecycle result. This is one of the simplest ways to prevent an apparently small protocol misunderstanding from becoming a false chain of actions.

Turn 202 Accepted into a state machine with evidence

A practical task state machine has at least local states such as submitted, accepted-pending, succeeded-verified, failed-verified and unknown. The precise names do not matter; their separation does. A request begins as submitted. A documented 202 admission moves it to accepted-pending. Only a server-specified terminal success signal, plus any necessary output validation, moves it to succeeded-verified. A terminal error becomes failed-verified. A transport timeout or ambiguous intermediate response remains unknown until reconciled.

Unknown is not synonymous with failed. A request may have reached the server and committed an operation just before the connection broke. If the agent instantly resubmits a side-effecting POST without a supported idempotency mechanism, it can create two jobs or two charges. Reconcile with the original task identifier, an application-level idempotency key where supported, or an authoritative resource read. Prefer does not itself make retries safe.

Status resources also need defensive treatment. Polling responses may be stale, access can expire, and one status page can be inconsistent with the final resource. A reliable agent records the original request identity, checks the service’s documented terminal states, validates any output digest or version if relevant, and refuses to claim task completion merely because the polling loop stopped.

Wait is a processing preference measured in seconds

The wait preference is a non-negative delta-seconds value representing an upper bound on how long the client expects the server to take processing the request once the server receives it. For example, Prefer: respond-async, wait=4 expresses interest in a synchronous result if that is feasible within about four seconds, while allowing asynchronous handling if the work takes longer. The server is allowed to ignore the preference. It does not create a client-side timer by itself.

Transport latency and intermediary processing sit outside that narrow processing window. A user who has a six-second visible deadline cannot safely conclude that wait=6 guarantees delivery by second six. Connection establishment, upload time, queuing, response travel and client rendering all consume budget. A robust caller sets its own end-to-end deadline and builds room for those components, then chooses a wait preference shorter than the remaining usable time where that is appropriate.

Because wait is advisory, the client must still handle a response that arrives sooner, later or not at all. It also must not interpret wait as a command to poll every N seconds. Polling cadence is a different contract, often influenced by server guidance, a Retry-After value when applicable, rate limits and the cost of repeated reads.

Worked time-budget case: six seconds is not six seconds of server work

Suppose a user-facing action must either show a verified result or clearly show pending within 6.0 seconds. The application budgets 0.3 seconds for local validation, 0.5 seconds for outbound network variability, 0.6 seconds for response travel and display, and 0.6 seconds for uncertainty reserve. That leaves 6.0 − 0.3 − 0.5 − 0.6 − 0.6 = 4.0 seconds as a planning allowance for the synchronous server path. Sending Prefer: respond-async, wait=4 expresses that preference, but does not enforce it.

If the server acknowledges pending at 0.7 seconds, the interface can honestly display ‘accepted, processing’ and enter its status-check route. If the server instead responds with a fully validated result at 3.2 seconds, the agent can complete normally. If a response has not arrived by the application’s independent six-second deadline, it reports uncertainty and reconciles rather than fabricating a cancellation or resubmitting blindly. These numbers are hypothetical engineering budgets, not measurements from a particular service.

Now change the context: a mobile user has a 2.5-second deadline and 0.9 seconds of expected combined overhead and reserve. A wait preference of four seconds no longer aligns with the user experience; 2.5 − 0.9 = 1.6 seconds remains for the synchronous processing preference. Choose a shorter wait only if the service supports it, or go directly to an asynchronous workflow. The correct answer changes because the underlying deadline changed.

Return=representation reduces read-after-write round trips

The return=representation preference asks for a representation of the current resource after successful processing. Imagine a PUT that changes a task title. The server may normalize whitespace, attach a revision, compute a derived status or set an updated timestamp. Without a representation, the client might need a subsequent GET to learn those authoritative values. A single response containing the current representation can avoid that extra request where the API honors the preference.

The returned entity is not necessarily a representation of the request URI itself when an operation acts on another resource. HTTP’s Content-Location field can identify the representation being returned in appropriate circumstances; clients should follow the service’s semantics. A client should never silently assume that arbitrary JSON from a successful response is the complete canonical state of the original resource. Validate type, scope, identity and version before writing it into local state.

Representation does not weaken concurrency requirements. A safe update still uses an appropriate precondition such as If-Match when the API supports optimistic concurrency, and still handles a rejected precondition. Asking for a fresh representation is useful for efficiency and confirmation, but it is not permission to overwrite a concurrent author’s changes.

Return=minimal saves bytes but can create a later read

The return=minimal preference requests a minimal successful response. Often that means 204 No Content, but the exact minimal shape is server-defined; some operations can legitimately use 201 Created with a Location header and no body. A client must not insist that every minimal response has status 204. Conversely, it must not treat an absent body as proof that all requested side effects took place unless the API’s success semantics establish that.

Minimal responses are useful when an agent already knows which resource it changed and needs only a verified acknowledgement. They are less attractive when the next decision depends on server-generated fields. Sending return=minimal for a create operation and then immediately issuing GET for a server-assigned identifier can add overhead rather than remove it. Account for the entire workflow, not the byte count of the immediate response.

These two return preferences are mutually exclusive. RFC 7240 notes that sending both is likely a client bug and can be handled as though neither were specified. If a planner constructs contradictory preferences, repair the request before dispatch instead of hoping that the server will choose whichever interpretation is most convenient.

Worked data-volume case: count bodies, not mythical savings

Assume a supported API normally returns a 6 KiB representation after each successful update, while its documented minimal response carries a 300-byte body or envelope. For a batch of 1,200 updates, the response payload avoided per update is 6 × 1,024 − 300 = 5,844 bytes. Across 1,200 updates, that is 7,012,800 bytes, or about 7.01 decimal megabytes of payload. It is roughly 6.69 mebibytes. The calculation deliberately excludes headers, TLS framing, compression, retries and transport overhead; actual network savings can differ.

Now assume every third update needs a follow-up 6 KiB representation anyway. Four hundred extra GET responses alone add 400 × 6,144 = 2,457,600 bytes of response payload, before counting requests or latency. The remaining net response-payload saving versus always returning the full representation is 7,012,800 − 2,457,600 = 4,555,200 bytes, about 4.56 MB. Whether minimal is beneficial depends on those later reads, cache behavior and whether the representation would have been compressed.

Do not claim that a 120-millisecond extra round trip multiplied by 1,200 requests equals 144 seconds of user-visible delay if requests are parallel. It equals 144 seconds of cumulative request latency in a sequential accounting; real elapsed wall-clock time depends on concurrency and bottlenecks. Reporting the denominator and execution model prevents an apparently persuasive but misleading efficiency claim.

Handling=strict and handling=lenient are about error tolerance

The handling=strict and handling=lenient preferences express a client’s desired approach to optional error handling. The server may be able to recover from a minor defect in submitted data and continue, or it may reject the request. The choice remains constrained by the service’s validation policy and by security and correctness obligations. Lenient is not a generic instruction to skip validation.

For example, suppose a text-import service receives three rows with valid columns and one row with an extra harmless whitespace field. A documented lenient mode might normalize the extra whitespace while keeping a precise record of what changed. That is different from silently accepting an unauthorized account identifier or ignoring a signature mismatch. The latter is not a permissible ‘repair’ simply because the client requested leniency.

For agents, strict handling often provides cleaner auditability in money movement, identity, legal documents and safety-critical changes. Lenient handling may help ingest messy but low-risk human input when the normalization rules are transparent and results can be reviewed. The agent’s plan should state which fields are allowed to be repaired, which must fail, and what evidence is retained; it should not treat the preference as a blanket guarantee.

Preference-Applied reports what was honored, not every fact about success

RFC 7240 defines the optional Preference-Applied response field to indicate which preferences a server honored. This is useful when the result could otherwise be ambiguous. A client can request return=representation and read Preference-Applied: return=representation in a successful response, for example. The field has its own syntax; it is not simply a copy of the original Prefer field with all parameters.

Even when Preference-Applied is present, examine the actual status code and body under the API contract. A server reporting that it applied minimal return does not prove that a particular business transaction has settled. A response reporting asynchronous processing does not mean the background job is complete. Treat the field as one corroborating signal about chosen optional behavior, never as a replacement for operation-level confirmation.

Do not hard-fail every response merely because Preference-Applied is absent. The header is optional, and RFC 7240 specifically recognizes circumstances where the server’s behavior is already obvious from the response. A resilient agent can log the requested preference, the observed status and representation, and the applied preference if provided, while basing correctness on authoritative resource or task state.

Prefer is not Expect, and neither is authorization

HTTP includes multiple request-header concepts that sound similar but serve different purposes. Prefer expresses optional desired behavior. Expect is associated with expectations about request handling under HTTP semantics, such as 100-continue in appropriate deployments. A server can ignore a preference; that fact would be intolerable for a security policy that depends on being enforced. Conflating these meanings creates logic gaps that rarely show up in happy-path demos.

Consider an agent that uploads sensitive records and includes Prefer: handling=strict. It would be unsafe to assume that adding those bytes guarantees strict authorization checks, particular retention policies or content scanning. Those are server responsibilities specified by the application contract, backed by access-control and validation systems. The agent must still confirm it is using the correct principal, endpoint, tenant and scope.

The same separation applies to output validation. A client cannot outsource parsing safety to return=representation, or timeout safety to wait. The protocol gives hints about representation and processing choices; it does not provide an entire threat model. Record independent controls such as credential scope, entity identifiers, ETags, idempotency, trusted URLs and allowed output types.

Vary: Prefer protects variants when preferences affect caches

RFC 7240 warns against using Prefer as content negotiation and explicitly discusses cache variation. When an origin supports optional preferences that can alter a cache’s handling of a response entity, it must indicate Prefer in Vary regardless of whether the request actually supplied Prefer, or use the permitted Vary wildcard. Without an appropriate Vary value, a shared cache might reuse a minimal representation for a client expecting a full one, or incorrectly reuse a representation produced under different preference handling.

Imagine a read endpoint that chooses between verbose and compact output shapes in response to a nonstandard preference. If the server permits such preference-dependent variation, the caching layer needs to understand that the representations differ. A Vary field can separate cache variants, but it does not validate that the underlying API design is wise. RFC 7240 encourages caution and says Prefer should not be used as a general content-negotiation replacement.

A client cannot fix a misconfigured shared cache simply by adding Prefer. Agents that see unexpected bodies should inspect response headers, representation identifiers, Content-Type and cache behavior, and should avoid making irreversible decisions until they have a trustworthy read. Cache keys, authenticated responses and origin-specific policies must be reviewed together.

A cache collision case with explicit requests and consequences

Consider two hypothetical clients reading one immutable document through a cache. Client A asks for an ordinary 8 KiB representation. Client B asks for a 100-byte summary using a server-defined preference. If the server generates two cacheable shapes but fails to distinguish them in a suitable Vary policy, a later cache lookup can deliver the 100-byte summary to Client A. Client A may parse an omitted field as an empty value and produce a false decision. The risk is semantic, not merely slower performance.

Suppose the server returns Vary: Prefer for both variants. That makes the request preference part of relevant cache selection under HTTP caching rules. It does not guarantee the cache is implemented correctly, or solve authorization leakage if the response should never have been shared. An engineering review must still check Cache-Control directives, private data, authentication and cache key normalization. The example numbers are illustrative and not a claim about any specific product.

One robust client policy is to fail closed on missing mandatory fields rather than defaulting them to empty strings. Another is to request an authoritative resource state through a documented endpoint when the response shape or ETag is not what the workflow expects. Both measures remain valuable even when the origin has implemented Vary properly.

A timeout cannot tell you whether the server committed the request

An agent submits a state-changing POST with Prefer: respond-async, wait=3. The socket times out at four seconds without any response. What happened? The request could have failed before reaching the origin. It could have been accepted for background processing. It could even have finished and lost its response on the return path. Prefer cannot distinguish these possibilities. The only honest local state is unknown until an independent reconciliation mechanism resolves it.

If the API supports idempotency keys for creates, the client should use a stable key for a logical operation, not generate a fresh key on every retry. If the API instead exposes a stable operation ID or searchable business key, the client can query that identifier. For updates, a conditional request can protect against conflicting writes. The exact choice is API-specific, and no universal HTTP header automatically makes arbitrary POST requests idempotent.

A useful tabletop calculation: among 100 independently submitted operations, suppose five response paths time out after the server has actually accepted all five. Blindly resubmitting them as new jobs yields 105 accepted jobs for 100 intended operations. That is a five-percent excess in this hypothetical batch. Reconciliation before retry prevents those duplicates when the server offers a reliable way to identify the existing operations.

Keep asynchronous task links inside the correct trust boundary

A 202 response may contain a Location or other reference to progress. The agent should not automatically follow any arbitrary URL supplied in a response with the same privileges it would use for the original API. Verify the allowed origin, authentication audience, scheme, tenant and resource binding. A status URL can be an attack surface for cross-origin credential leakage or server-side request forgery if a program treats it as trusted solely because it appeared in a header.

Likewise, a returned representation might contain links or embedded instructions that are data rather than commands. A model-assisted agent should not let those fields override the user’s objective, access policies or the calling application’s tool boundaries. Header parsing and document parsing are both inputs to an untrusted-data workflow. Use allowlists or contract-aware URL validation, distinguish content from executable authority, and avoid storing unvalidated secrets in logs.

Defensive design also involves resource limits. A server could be slow or repeatedly advertise pending state. The agent needs maximum polls, elapsed-time budgets, backoff policy, authorized cancellation where available, and a clear route to report unresolved status. These controls protect the user and the server from indefinite spinning and accidental cost amplification.

A practical API contract for pending work

RFC 7240 deliberately does not specify a universal asynchronous job protocol. If you design an API, document what 202 means, where progress can be queried, the shape of pending and terminal responses, whether the task can be cancelled, how long status records remain available, whether the client can supply an idempotency key, and what counts as authoritative proof of completion. A Preference-Applied field can improve observability but cannot fill in these missing contracts.

One sensible design separates an operation resource from an output resource. The operation resource reports state and error information; the output resource is referenced only after success and can be fetched under appropriate authorization. If an agent gets 202 and a status URI, it should not treat that URI as the final deliverable. On success, check the response’s actual output identity, access control and data integrity, then update downstream workflow state.

If a task has multiple phases, such as accepted, running, verifying and succeeded, describe the transitions explicitly. Progress percentages are presentation, not proof. A job marked 100 percent might still need output validation. An operator should be able to reconcile by durable operation identity after restarts, tool errors and network splits.

Client algorithm: branch on observed behavior, not requested behavior

A robust client begins by validating a logical operation and its authorization. It establishes a stable request identity, records any concurrency preconditions, sets an independent deadline, then attaches preferences supported by the API. After receiving a response, it reads the HTTP status, media type, documented body schema, operation identifier and any Preference-Applied indication. Only after those checks does it decide whether to treat the operation as pending, completed, rejected or unknown.

For a synchronous success with a representation, validate that the returned resource corresponds to the intended target and carries whatever revision evidence the application needs. For a minimal success, do not fabricate absent fields; retrieve the resource if downstream steps require it. For an asynchronous acceptance, record the operation identity and schedule controlled reconciliation. For an ambiguous timeout, ask the server what happened before retrying a non-idempotent operation.

At every branch, the user’s visible message should match actual knowledge. ‘Request accepted and still processing’ is appropriate for documented pending work. ‘Update verified’ requires reliable success evidence. ‘We cannot yet tell whether the update applied’ is a legitimate outcome when the server cannot disambiguate a network failure. The sentence may be less comforting, but it is safer than inventing certainty.

Server algorithm: decide, report and constrain

A server first validates the method, resource, request body, authentication and authorization independently of any optional preference. It parses recognized Prefer tokens and decides which may be honored under its documented policy. If the work can finish within practical limits, a synchronous completion can be returned. If an accepted asynchronous workflow exists and respond-async is supported, the server can acknowledge it while providing the agreed tracking mechanism. If it cannot support such a workflow, it must not pretend that a background job exists.

For return preferences, the server chooses a success response consistent with HTTP and its resource contract. When selecting a representation, it should return a consistent resource shape and useful identifiers. When selecting minimal output, it should avoid accidentally omitting information the documented contract requires. It can include Preference-Applied to make its optional choice visible. Cacheable variants require an appropriate Vary policy as specified by RFC 7240.

Operationally, the server should record queue admission and completion as separate events, retain enough state for reconciliation, and ensure that retries cannot accidentally bypass application-level uniqueness protections. These are server engineering responsibilities. The client’s preference can express its willingness to cooperate, but the server must enforce its own invariants.

WebDAV extension: a useful example of narrower, specified behavior

RFC 8144 updates the Prefer header’s use in WebDAV. It makes certain minimal-response expectations more precise for operations such as PROPFIND and REPORT, where response bodies can contain multiple property statuses. This illustrates an important design principle: a generic preference becomes operationally reliable only when the specific protocol and server explain what honoring it means.

For example, RFC 8144 describes omitting particular 404 property-status elements from relevant multi-status responses under return=minimal, subject to conditions. A client must still parse the remaining response correctly and respect the WebDAV operation’s status semantics. It must not generalize these WebDAV-specific details to unrelated JSON APIs. A spreadsheet-sync agent, a calendar client and an object-storage uploader may all send Prefer, but their actual minimal responses can differ legitimately.

This article is about preference negotiation, not the separate problem of interpreting WebDAV 207 Multi-Status per-resource results. Readers needing that distinction can use the related guide on per-resource WebDAV outcomes; treating one overall HTTP code as universal success is a different error from misunderstanding a requested response preference.

Do not confuse respond-async with HTTP 103 Early Hints

HTTP 103 Early Hints is an informational response mechanism associated with sending selected hints before a final HTTP response, often to help clients begin loading related resources. It is not an acceptance record for a long-running background job. By contrast, respond-async is a request preference, and a resulting 202 Accepted response is a final HTTP response for that request that reports an accepted but unfinished operation under HTTP semantics.

A parser that treats every non-200 response as either an error or completion will mishandle both patterns. A 103 precedes another response. A 202 is not itself a terminal business success for an asynchronous operation. The distinction matters for a model-assisted crawler or document workflow that could otherwise mark files as ready when it only saw a transport-level hint or queue acknowledgement.

For additional context, the site’s guide to HTTP 103 Early Hints and final responses covers that different mechanism. Keeping related but distinct concepts in separate reading pathways reduces both teaching confusion and unsafe implementation shortcuts.

Do not confuse response preferences with PATCH semantics

A response preference changes how an agent asks to hear back; a mutation format defines how the resource is changed. JSON Merge Patch, for example, uses a documented patch representation in which null has deletion implications and arrays are replaced as whole values. Choosing return=representation after such a patch can help the client inspect the authoritative resulting resource, but it does not make an ambiguous patch safe or grant permission to apply it.

A robust sequence for a documented conditional patch is: read the current resource and version, construct the smallest semantically correct patch, send the appropriate precondition, request a useful response representation if supported, then validate both the response and the target’s identity. If the server rejects the precondition, refresh and reconcile rather than force an overwrite. A minimal response may be enough only when the agent has no further decisions dependent on updated fields.

The related article on JSON Merge Patch, null deletion and safe preconditions explains the mutation side. The two guides solve different jobs: one is about what operation is performed; this one is about how the client expresses optional response-processing choices.

What to log without leaking private information

Useful observability separates intention from outcome. For each logical operation, record a locally generated operation ID, the API endpoint identity, method, relevant preference tokens, timing budget, request outcome, observed status code, whether Preference-Applied was returned, task identity when present, and eventual reconciled state. Redact credentials, sensitive query parameters and private body data. Logs should not become a second accidental storage system for user information.

Distinguish an HTTP duration metric from end-to-end task duration. A 202 response in 180 milliseconds might precede ten minutes of backend processing. Reporting only 180 milliseconds as ‘task finished in’ would be misleading. Likewise, measuring response bytes for return=minimal says little about user experience if every operation then requires a slow GET. Report time to verified completion, pending queue time, number of polls, follow-up reads, retries and duplicate-operation incidents separately.

For alerts, monitor growth in unknown outcomes, unusually many pending tasks, repeated duplicate idempotency keys, missing terminal states and unexpected response shapes. These symptoms can signal faults in either client assumptions or server contracts. They are more actionable than a generic success-rate chart that treats every 2xx status as proof of finished work.

A test matrix for agents before production use

Test that an unsupported preference is ignored gracefully. Test a server that honors respond-async but ignores wait, and another that completes synchronously even when async is preferred. Test a 202 with a valid status URI, a 202 with an unexpected link, a 202 with a missing task reference under a contract that requires it, a 204 with no body, and a 200 representation with missing required fields. Each outcome should take a documented client branch rather than falling through to optimistic success.

Test duplicate Prefer tokens, contradictory return values, multi-line field combinations, unexpected casing, malformed wait values, delayed responses, connection resets after server commit, an expired polling token, throttled status checks and a stale cache variant. Use controlled test fixtures with deterministic task outcomes to avoid interpreting a flaky integration as proof that your error path works.

Finally, perform a changed-context test: the same logical operation moves from a fast internal network to a high-latency mobile client. Does the agent reduce its assumed synchronous processing window and continue to report pending honestly? Does it preserve request identity across handoff? Does it refrain from resubmitting a timed-out write as a brand-new action? A design that passes only its familiar network conditions has not demonstrated reliable behavior.

End-to-end case: an education report generation agent

Consider a hypothetical application that generates a 40-page teaching report from reviewed data. The user confirms one request and expects an honest progress indicator. The agent assigns operation key R-204, checks the output scope and sends POST to the report API with Prefer: respond-async, wait=3, return=minimal, if that combination is supported in the API contract. The API acknowledges with 202, a task reference and appropriate authentication requirements. The agent does not announce that the report exists.

Suppose the status service returns pending at t=2 seconds, running at t=5 seconds and completed at t=11 seconds. The agent validates the completed state, retrieves the output resource under the correct permissions, checks the expected report format and only then says that the report is ready. The three poll timestamps and a particular result are hypothetical; the example illustrates a sequence, not an observation. A previous 202 has not been retrospectively promoted into proof of success.

Now add a network failure at t=3 seconds, just after the server admitted the job. The agent’s recovery routine looks up R-204 rather than creating R-205 for the same logical request. If the server lacks a reliable idempotency or lookup contract, the agent displays an unresolved state and asks for safe reconciliation rather than launching a duplicate report with possible costs. This is a practical expression of safe uncertainty.

Transfer challenge: from reports to calendar booking

Transfer the mechanism to a calendar-booking API. An agent must create one event, then immediately invite participants. It requests return=minimal to save bytes, but the server generates the final event ID and the canonical time-zone-adjusted start time. Is minimal still a good preference? Not if invitations depend on those fields and a second GET is expensive. Prefer return=representation when supported, then verify the identity, time zone and version before sending invitations.

Next, suppose the same booking API can take 30 seconds when reconciling external calendars. Respond-async may become useful, but the agent must defer invitations until it sees authoritative completion. A pending operation does not reserve a room merely because the server accepted the request. If another organizer changes the room concurrently, a conditional update or explicit conflict response remains essential.

Finally, imagine a high-risk booking involving medical appointments. Even a complete-looking response does not authorize broadcasting sensitive details to participants outside the verified recipient list. The workflow has at least three independent gates: correct request and authorization, confirmed committed resource state, and permitted downstream communication. Prefer helps with transport negotiation but does not replace any of the gates.

Choosing among preferences in a real integration

Use respond-async when the service explicitly documents a pending-work protocol and the client is prepared to track completion. Pair it with wait only when the server supports meaningful wait handling and a client-side end-to-end deadline is separately enforced. Choose return=representation if the next step needs canonical updated fields and the server supplies a trustworthy representation. Choose return=minimal if the caller truly needs no additional fields and avoiding response payload has measurable value.

Strict-versus-lenient preferences require particular care because the allowed error recovery must be defined by the application. Prefer strict handling for audit-sensitive or high-risk workflows unless a documented recovery policy justifies something else. Do not assume any token is universally implemented. Probe capabilities through official API documentation and controlled tests, not by observing one happy-path response.

A useful decision record names the actual problem, states the requested preference, lists which behaviors the server is free to choose, defines the independent correctness checks and describes recovery after uncertainty. If the record cannot explain how a pending request becomes verified completion, the workflow is incomplete regardless of how elegant its HTTP header looks.

Limits: what this standard deliberately does not solve

RFC 7240 does not standardize job identifiers, progress percentages, polling intervals, cancellation, callback signatures, operation idempotency, authorization, business success or an end-to-end deadline protocol. It does not require all HTTP servers to support every named preference. It does not make conflicting return directives sensible, and it warns about cache impacts when response variants differ. Those boundaries are features of a narrow general-purpose mechanism, not defects that a client should silently paper over.

Some APIs use proprietary headers or request-body fields rather than Prefer to select asynchronous behavior. Others have a dedicated jobs endpoint, WebSocket stream or webhook protocol. The right engineering choice is to honor the target service’s documented contract rather than force a generic header onto an endpoint that ignores it. A service can also define a synchronous-only operation for which respond-async brings no benefit.

The safest default is to treat every unverified result as an observation with limits. The header helps clients express preferences politely. It cannot turn an uncertain side effect into a known one, and it cannot confer greater authority on an AI agent than the user or application granted.

Frequently asked questions

Does Prefer: respond-async force HTTP 202? No. It says the client prefers asynchronous behavior; a server may ignore it, complete synchronously, or implement its own documented asynchronous pattern. The client branches on the actual response and service contract.

Does wait=5 cap the total request at five seconds? No. It is a processing-time preference measured in seconds. Network time, intermediary processing, application deadlines and user interface time require separate accounting. Servers can also ignore the preference.

Is a 202 response a completed operation? No. It acknowledges accepted processing, not a terminal business outcome. Verify completion through the API’s defined mechanism and validate any promised output.

Can an agent send return=minimal and return=representation together? It should not. RFC 7240 treats them as mutually exclusive and notes that a server can handle the conflicting request as though neither were present. Fix the caller.

Is Preference-Applied mandatory? No. It is an optional response field for revealing which preferences were honored when useful. Its absence does not always mean a preference was ignored.

Does return=representation remove the need for concurrency control? No. It can reduce a follow-up GET, but it does not prevent a stale write from overwriting concurrent work. Use the API’s version and precondition mechanism.

Can handling=lenient permit unauthorized records or bad signatures? No. A preference cannot override mandatory security or application invariants. Document any allowed normalization and validate its result.

Should a proxy cache variants produced under Prefer without Vary? Not when honoring a preference can change cache handling of the entity and RFC 7240’s conditions apply. The origin needs appropriate Vary treatment and sound general caching policy.

What if a request times out after submission? Treat its business outcome as unknown until reconciled. Use the service’s operation lookup, stable idempotency key or authoritative read; do not assume failure and resubmit a new side-effecting operation.

Does any of this prove artificial superintelligence exists? No. The examples describe current HTTP, software agents, and safety practices. Artificial superintelligence remains a hypothetical category, not a present verified system described by this article.

Primary standards and suggested next reading

The protocol claims in this guide are grounded in the original IETF standard RFC 7240, Prefer Header for HTTP (June 2014), the modern HTTP semantics specification RFC 9110, HTTP Semantics (June 2022), and the more specific RFC 8144, Use of Prefer in WebDAV (April 2017). These direct primary URLs provide normative distinctions; any site-specific API must still be checked against that vendor’s own current documentation.

To continue the agent-engineering pathway, read the verified articles on HTTP 103 Early Hints and the final response and JSON Merge Patch and safe resource updates. The first helps distinguish informational replies from final HTTP outcomes; the second explains why correct state mutation is independent of response-size preference.

For the larger map of current agent and system engineering, use the How Super Intelligence Works guide. Remember the governing boundary: tools, workflows and agent architectures are real contemporary engineering; no claim in this pathway depends on artificial superintelligence already existing.

Discover more from eduKate Singapore

Subscribe now to keep reading and get access to the full archive.

Continue reading