API Response Wrapping Fix Prompt

This prompt is for integration engineers and backend developers who receive model-generated API payloads that violate the expected envelope structure. The core job-to-be-done is correcting malformed HTTP response wrappers—such as a missing top-level data key, an incorrect status field, or a wrong Content-Type—before the payload is returned to a client or processed by downstream services. The ideal user is someone who already has a valid OpenAPI or GraphQL schema and needs the model to self-correct its output to match that contract, using few-shot examples of the correct envelope pattern.

Use this prompt when the model consistently produces structurally invalid API responses that fail client-side parsing or middleware validation. It is most effective when the semantic content inside the payload is correct but the wrapper is wrong—for example, the model returns { "user": {...} } instead of { "data": { "user": {...} }, "status": 200 }. The prompt relies on providing the target schema and concrete wrapping/unwrapping examples. Do not use this prompt to fix deeply nested semantic errors, business logic violations, or authorization issues; those require different repair strategies. You must supply the expected envelope schema as part of [CONTEXT] and at least two contrasting examples in [EXAMPLES]—one showing the malformed input and the corrected output, and another showing a correctly wrapped response for reinforcement.

Before wiring this into a production pipeline, define a validation step that checks the repaired output against your API contract using a schema validator. If the repair fails validation, escalate to a retry with a more explicit error message or route to a human reviewer for schema-level failures. Avoid using this prompt as a permanent fix; if wrapping errors are frequent, revisit the upstream system prompt or model choice. The next step is to copy the prompt template and adapt the [SCHEMA] and [EXAMPLES] placeholders to match your specific API envelope.

This template provides a production-ready prompt for repairing model-generated API responses that violate the expected envelope structure. It is designed for integration engineers who need to correct malformed JSON payloads—such as missing status fields, incorrect Content-Type headers, or wrong top-level keys—before the response reaches a client or downstream service. The prompt uses few-shot examples to demonstrate the correct wrapping pattern, making it more reliable than instruction-only approaches for complex nested schemas.

textCopy
You are an API response repair system. Your job is to take a malformed API response and rewrite it to match the expected envelope structure defined by the target API specification.

[API_SPECIFICATION]

[EXAMPLES]

## Instructions
1. Analyze the [INPUT] response against the specification above.
2. Identify all structural violations: missing or extra top-level keys, incorrect status fields, wrong content types, or malformed data payloads.
3. Apply the corrections demonstrated in the examples.
4. If the data payload itself is valid but wrapped incorrectly, preserve the payload content and fix only the envelope.
5. If the data payload is also malformed, flag it with a `"repair_note"` field in the corrected response.
6. Output ONLY the corrected JSON response. Do not include explanations, markdown fences, or commentary.

[INPUT]

Adaptation guidance: Replace [API_SPECIFICATION] with a concise description of the expected envelope, such as {"status": "success|error", "data": {...}, "meta": {"timestamp": "ISO8601"}}. Populate [EXAMPLES] with 3–5 input-output pairs showing common wrapping errors and their corrections. The [INPUT] placeholder should receive the raw, malformed model output at runtime. For high-risk APIs (payments, health data), add a [CONSTRAINTS] block requiring human review when the repair confidence is low or when the data payload itself is altered. Always validate the corrected output against the target schema before returning it to the client.

The API Response Wrapping Fix Prompt is designed to sit inside a repair loop that activates after your primary generation step produces a response that fails an envelope contract check. Do not call this prompt on every response—only when a lightweight structural validator (checking for the presence of data, errors, statusCode, or the expected GraphQL data/errors wrapper) returns a failure. This keeps latency and cost low for the 90%+ of responses that are already well-formed. The prompt expects the malformed raw output and the target API contract (OpenAPI response schema or GraphQL operation definition) as inputs, and it returns a corrected payload that should pass the same validator.

Integration flow: 1) Primary model generates a response. 2) A structural validator checks for the required envelope fields and content-type headers. 3) On failure, the raw output and the expected schema are passed to this repair prompt. 4) The repaired output is re-validated. 5) If it passes, return it to the caller; if it fails again, log the failure and either escalate to a human reviewer or return a controlled error response. Model choice: This repair task benefits from models with strong instruction-following and JSON manipulation capabilities. GPT-4o, Claude 3.5 Sonnet, and Gemini 1.5 Pro all perform well. Avoid smaller or older models (e.g., GPT-3.5-turbo) for nested envelope repairs, as they tend to hallucinate field values when restructuring. Validation: Use a deterministic post-repair validator that checks: (a) the top-level keys match the expected envelope, (b) required fields like statusCode or errors are present and of the correct type, (c) the Content-Type header or wrapper implies the right format (e.g., application/json), and (d) nested payloads parse correctly. Do not rely on the model's self-report of success.

Retries and failure modes: Set a maximum of 2 repair attempts. If the first repair fails validation, feed the validator's specific error message back into the prompt as additional context for a second attempt. If the second attempt also fails, stop retrying. Common failure modes include: the model inventing data to fill missing required fields (mitigate by instructing it to use null or explicit error markers), the model changing the semantic content of the payload while fixing the envelope (mitigate by diffing the pre-repair and post-repair inner payloads and flagging changes >5% for review), and the model wrapping an already-correct payload in a second envelope layer (mitigate by checking for double-wrapping in the validator). Logging: Log every repair invocation with the original output, the repair prompt used, the repaired output, the validation result, and the number of attempts. This data is essential for detecting prompt drift—if the repair rate suddenly increases, your primary prompt or model behavior has likely changed. Human review: For APIs in regulated domains (payments, healthcare, legal), route any twice-failed repair to a human review queue rather than returning a potentially malformed response to the end user. The repair prompt is a production safeguard, not a substitute for correct primary generation.