Retry extractions with precise error feedback

Learning objective

Retry correctable extractions with the original document, the failed extraction, and exact validation errors.

Core idea

A correction request needs three inputs: the original source, the failed record, and the specific validation errors. The source supplies the evidence, the record identifies what needs correction, and the errors direct attention to the failed checks. “Try again” supplies none of that diagnosis.

Anthropic documents self-correction as a chain of separate calls: generate, review against criteria, and refine. In this extraction flow, application validators supply the review criteria and failure details. Your application then validates the replacement record before accepting it; a second answer is not automatically a better answer.

See 4.4.1 for producing semantic errors and 4.4.3 for deciding whether supplied evidence makes another attempt worthwhile. This lesson owns how you package a correctable failure into a follow-up request.

How it works

Make each error actionable

Name the field, the observed value, the failed relationship, and the evidence the model should inspect. For example, an invoice extractor returns stated_total: 142000 in cents while the extracted charges support 124000; a source check confirms the printed quote “Total 1,240.00.” A useful error says that the extracted stated amount differs from the printed “Total 1,240.00,” and asks for a reread of that location.

Avoid presenting a numerical discrepancy as proof of which field is wrong. “Set stated_total to sum(charges)” would erase a genuine source conflict. Instead, ask the model to check the total and the components against their labels, preserve printed values, and report any source inconsistency. The validator diagnoses the failed relationship; the source determines the correction.

A date error also needs context. “invoice_date contains the value labeled Due date; inspect the separate Invoice date label” is more useful than “invalid date.” If the problem is formatting, state the expected convention and the source value. If the source is ambiguous, retain that ambiguity rather than inventing a convention to satisfy the validator.

Retain the complete correction context

The Messages API is stateless: each request includes the conversation history you want Claude to use. A prior document does not become accessible to a subsequent request merely because your application remembers sending it.

You can continue a valid message history containing the document and failed extraction, or build a fresh request that explicitly supplies both. In either case, inspect the request assembled by the application: it must contain the evidence, the failed values, and the error details. A reference to an internal document identifier is insufficient unless the document content is actually available in that request’s workflow.

Keep the output contract the same. For tool extraction, retain the relevant tools definition and input_schema; for native JSON extraction, retain output_config.format. The correction should improve the values, not relax the schema so an invalid result passes. See 4.3.2 for choosing between those output interfaces.

Return validation failures through the tool protocol

When an extraction tool’s execution includes validation and fails, return a tool_result for the corresponding tool_use block. Set tool_use_id to that call’s exact id, put the error details in content, and set is_error: true.

After a source check confirms the printed total, a user message for an application-defined extract_invoice tool might contain this result block:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "TOOL_USE_ID",
      "is_error": true,
      "content": "Validation failed: stated_total=142000 cents, but the supplied invoice's Total label reads 1,240.00. Re-read that label and the charges. Preserve source values and call extract_invoice with the corrected complete record."
    }
  ]
}

Replace TOOL_USE_ID with the actual call identifier. The retained history contains the source document and the assistant’s failed tool_use.input; the block supplies the third input, the error feedback. This is a protocol fragment, not a standalone API request.

Tool results must immediately follow the corresponding assistant tool-use message in the history. Within the user message, result blocks precede any other text. If there are multiple tool calls, answer their results rather than inserting a separate correction message between the calls and their results. Keep this extraction flow limited to its client tool; mixed server-tool turns have additional ordering requirements described in the tool-call documentation.

For native JSON output, no extraction tool call exists to answer. Include the failed JSON and validator errors in the follow-up user content, with the original source still available in the supplied history. Do not manufacture a tool_result without a matching call.

Validate the entire replacement

After the correction, apply the same structural and semantic checks to the complete replacement record. A focused correction prompt can reduce unnecessary changes, but it does not guarantee that unrelated fields remain accurate. Rechecking only the originally failed field can miss a regression elsewhere.

Set an application correction limit before the loop starts. For example, a service can allow one initial extraction and at most two correction requests; that is an example policy, not an Anthropic default. On exhaustion, retain the failed record and errors for review. If classification changes to missing evidence or verified source conflict, leave the correction path immediately.

Each correction round returns the exact errors and validates the complete replacement, until the record passes or the limit is exhausted.

Key distinctions and trade-offs

Validation retry versus repeating the prompt: A validation retry changes the diagnostic context. An unchanged request repeats the conditions that produced the failure.

Correction versus source repair: You repair a transcription or interpretation defect in the record. You do not rewrite a contradictory document to make its fields agree.

Tool result versus user feedback: A real tool call receives a matching tool_result. Native JSON output receives ordinary follow-up content. Both need the source, failed output, and specific errors.

A full-document follow-up gives the model enough context to check interactions among fields. Restricting the correction to a single snippet can hide a relevant label or adjustment elsewhere. Choose the evidence package from the failed rule, rather than removing context merely to shorten the request.

Architecture / decision scenario

An invoice pipeline extracts a printed total incorrectly and places a due date in invoice_date. Its validators identify both errors. The source contains distinct labels for each date and the printed total, so the failures are correctable from supplied evidence.

The application retains the original user document and failed assistant tool call. It returns one error tool_result with the matching tool_use_id, is_error: true, and both field-specific diagnoses. The instruction asks for a complete corrected record while preserving printed facts and flagging real inconsistencies.

The next extraction corrects the amount but still copies the due date into the invoice-date field. The application reruns every check, sends the remaining exact error within its correction limit, and validates again. If the limit expires, it records the unresolved date failure rather than accepting the amount fix as overall success. For a native JSON implementation, the same three inputs travel in a follow-up request without a tool-result block.

Common exam traps

• Sending “validation failed” without naming the failed fields or relationships.
• Sending only the errors and assuming the API remembers the document.
• Replacing the failed extraction with a prose summary that omits its values.
• Inserting a correction message before the required tool results.
• Creating a tool_result for native JSON output with no matching tool call.
• Validating only the corrected field or retrying beyond the application’s limit.

What to remember

Send the original source, failed extraction, and exact errors together. Use a matching error tool_result for tool execution, or ordinary follow-up content for native JSON. Preserve the contract and validate the complete replacement before accepting it.

Knowledge check

References

• Anthropic, Prompting best practices
• Anthropic, Using the Messages API
• Anthropic, Handle tool calls
• Anthropic, Structured outputs