Machine-readable Claude output needs an explicit contract at the boundary with downstream software. Structured outputs can constrain a response to a JSON Schema, and strict tool use can constrain tool inputs, but neither establishes that an extracted field is factual, policy-compliant, or appropriate to execute. Build a second semantic-validation layer and a controlled recovery path.
Select JSON Schema output or strict tool use for the relevant interface, inspect completion state and validate schema conformance before semantic correctness, then classify failures and retry only plausibly transient cases within a finite budget. Before repeating an uncertain side effect, use a stable idempotency key and outcome lookup; for Message Batches, prevalidate records, reconcile every result by custom_id after the batch ends, revalidate it, and only then commit downstream.
Separate Shape Validation from Meaning Validation
JSON Schema describes a permitted data shape: required fields, types, enumerations, and related constraints. Anthropic documents structured outputs as schema-constrained, parseable output for downstream processing and provides JSON Schema through output_config.format.
Schema validity answers whether the result conforms to that shape. Semantic correctness answers different questions: whether the value is grounded in the source, allowed by policy, current, internally consistent, and safe for the requested action. A valid priority: "high" field does not prove that the priority is justified.
Place semantic checks in code or a controlled review workflow. For a support classifier, that may include allowed-category checks, source-reference verification, confidence thresholds, duplicate detection, and a queue for uncertain cases. These checks are architectural recommendations; their exact rules must come from the application’s accountable owners.
Choose the Appropriate Output Mechanism
Anthropic documents two complementary structured-output capabilities: JSON Schema output for Claude responses and strict tool use for tool inputs. Availability is model and platform dependent, and the documentation identifies eligibility exclusions; verify support for the selected model and deployment before making it a required control.
Use JSON Schema output when an application needs a typed result to parse. Use strict tool use when Claude is choosing arguments for a tool whose contract must be constrained. Do not treat a schema as authorization: an application should still validate the requester, verify resource ownership, and decide whether the proposed tool operation is permitted.
Handle Documented Structured-Output Exceptions
Downstream code must validate the response content and stop_reason; a successful HTTP response is not by itself proof of schema-valid output. Anthropic documents that a safety refusal has stop_reason: "refusal" and can return HTTP 200 while the refusal text takes precedence over the schema. A response stopped at max_tokens can also be incomplete and fail the schema. Route a refusal to the application’s safe fallback or review path; for an incomplete response, decide whether a larger output limit and a bounded retry are appropriate.
Anthropic also documents an exception for the capitalization of string enum and const values: an otherwise normal response can differ only in casing. Compare those values case-insensitively where that is safe, and avoid values differentiated only by capitalization. Finally, schema compilation can reject unsupported schema features or fail when the combined schema is too complex, including after explicit limits pass. Treat these as request-design failures: simplify or split the schema, check the documented supported subset, and surface a clear validation error rather than retrying unchanged input.
Design Failures and Retries Deliberately
Tool and model failures should have named categories: transient service failure, invalid request, schema or semantic rejection, timeout, and side-effect uncertainty. Anthropic’s tool-use guidance documents returning tool-result errors so Claude can react to a failed tool call; it does not eliminate the need for application-level error handling.
Retry is an architectural recommendation, not a default remedy. Retry only failures that are plausibly transient, use a finite budget and backoff, and retain the original request identifier and validation result. A semantic rejection is usually a signal to repair inputs, revise the workflow, or escalate—not to repeat an identical request until it happens to pass.
Make Side Effects Idempotent
Before retrying an action that creates, changes, or sends something, design an idempotency key and an outcome lookup. Persist the key, the request fingerprint, the downstream response, and the final status. If the client times out after a downstream action may have occurred, reconcile with the target system before sending it again. This is a general operational pattern; it is not a guarantee provided by the Claude API.
Use Message Batches for Asynchronous Volume
The Message Batches API accepts a list of Messages requests for asynchronous processing. Each request needs a unique custom_id; use it as the stable reconciliation key, because results can be returned in any order rather than input order.
A safe batch lifecycle is: validate records before submission; assign a unique stable custom_id; store the batch identifier and source version; poll until the documented processing_status is ended; then reconcile and validate each individual result before committing it to a downstream system. Batch completion and result validation are asynchronous. A batch can contain succeeded, errored, canceled, or expired results, so do not make a whole-batch success assumption without inspecting each result.
Use the reconciled custom_id and result type to decide recovery. Repair an invalid request before resubmitting it; a transient error may qualify for the bounded retry policy; canceled or expired records need an explicit requeue decision. Preserve the original idempotency key and outcome lookup so a retry cannot duplicate a downstream side effect. These recovery rules are application architecture recommendations built on the documented batch result semantics.
Batch suitability depends on latency and recovery needs. Asynchronous processing is useful for independent, high-volume work that can tolerate delayed completion. It is a poor fit for a synchronous user decision or an action that must be immediately reconciled. Pricing, capacity, time limits, and model availability change; consult the current documentation before relying on them.
Common Output-Contract Mistakes
One mistake is asking for JSON in a prompt and assuming a parser will never see prose. Another is treating a response that passes JSON Schema as evidence that its claims have been verified. A third is retrying a timed-out write without knowing whether the write succeeded.
Keep raw input, model response, schema-validation outcome, semantic-validation outcome, and downstream action state separate in the audit record. Redact sensitive content and limit retention to the application’s policy. This separation makes an incident diagnosable and prevents output formatting from being confused with correctness.
Conclusion
Structured outputs turn an informal response boundary into a parseable interface, but the interface is only the first control. Combine JSON Schema or strict tool use with semantic validation, idempotent recovery, and per-record batch reconciliation. The next design concern is keeping long-running workflows within a useful context budget.