Structured Error Body Extraction Prompt

This prompt is designed for API consumers and integration engineers who need to parse heterogeneous error responses programmatically. It extracts error codes, messages, details, and remediation hints from raw API error payloads and normalizes them into a consistent schema. Use this when you are building an error aggregation pipeline, a multi-service client library, or an observability dashboard that must consume errors from APIs with different error body formats. The prompt handles undocumented fields, malformed JSON, nested error objects, and vendor-specific extensions.

This prompt is not a replacement for a schema validator or an OpenAPI spec parser. It is a normalization layer that sits between raw HTTP responses and your structured logging or alerting system. Do not use it when you have a strict, single-source API contract and can rely on static parsing—direct deserialization into typed objects is faster and more predictable for known schemas. The prompt adds the most value when you are consuming errors from multiple services, legacy APIs without formal specs, or third-party endpoints where error body formats drift over time. It also serves as a fallback when primary parsing fails, capturing partial structure from malformed payloads that would otherwise be discarded.

Before deploying this prompt, ensure you have access to the raw response body, HTTP status code, and any relevant headers such as Retry-After or rate limit indicators. The prompt expects these as input context. If you are operating in a high-throughput pipeline, consider caching normalized outputs for identical error signatures and implementing a circuit breaker that falls back to raw body logging when the model is unavailable. For regulated environments where error details might contain PII or secrets, apply redaction before the prompt sees the payload, and always log the original response alongside the normalized output for auditability.

This prompt template normalizes heterogeneous API error responses into a consistent, machine-readable schema. It is designed for integration engineers, observability pipeline builders, and SDK developers who need to parse error bodies from multiple services—each with its own format—into a single structured record that downstream systems can consume reliably. The prompt handles common patterns: JSON problem details (RFC 9457), vendor-specific error wrappers, HTML error pages, and even empty or truncated responses. It does not attempt to classify root causes or suggest remediation steps; those are separate downstream tasks that consume this normalized output.

textCopy
You are an error body extraction system. Your job is to parse a raw API error response and produce a structured JSON object. Do not guess. Do not invent fields. When information is missing, mark it as null and set the confidence to 0.0.

## INPUT
Raw error payload:
[RAW_ERROR_BODY]

HTTP status code: [HTTP_STATUS_CODE]

Response content type: [CONTENT_TYPE]

API or service name: [SERVICE_NAME]

## OUTPUT SCHEMA
Return exactly one JSON object with this structure:
{
  "error_code": string | null,
  "error_message": string | null,
  "error_details": array of strings | null,
  "error_category": string | null,
  "http_status_code": number,
  "retryable": boolean | null,
  "retry_after_seconds": number | null,
  "rate_limit_remaining": number | null,
  "rate_limit_reset_epoch": number | null,
  "documentation_url": string | null,
  "request_id": string | null,
  "raw_body_preserved": string,
  "field_confidence": {
    "error_code": number (0.0 to 1.0),
    "error_message": number (0.0 to 1.0),
    "error_details": number (0.0 to 1.0),
    "error_category": number (0.0 to 1.0),
    "retryable": number (0.0 to 1.0),
    "retry_after_seconds": number (0.0 to 1.0),
    "rate_limit_remaining": number (0.0 to 1.0),
    "rate_limit_reset_epoch": number (0.0 to 1.0),
    "documentation_url": number (0.0 to 1.0),
    "request_id": number (0.0 to 1.0)
  },
  "parsing_notes": string | null
}

## EXTRACTION RULES
1. **error_code**: Extract the most specific error code string (e.g., "invalid_api_key", "rate_limit_exceeded", "E1004"). Look in JSON fields named "code", "error_code", "type", "errorType", or the first element of "errors" arrays. If the body is HTML or plain text, set to null with confidence 0.0.
2. **error_message**: Extract the human-readable error description. Prefer the most specific message over generic fallbacks. Look in fields named "message", "error", "detail", "description", or "title".
3. **error_details**: Collect any additional error context such as field-level validation errors, parameter names, or nested error objects. Return as an array of strings. If none found, set to null.
4. **error_category**: Classify into one of: "authentication", "authorization", "validation", "rate_limit", "server_error", "client_error", "not_found", "conflict", "service_unavailable", "unknown". Base this on the HTTP status code and error body content. Do not invent categories.
5. **retryable**: Boolean. True if the error is transient (5xx, 429, some 409s) and the body or headers suggest retry is safe. False for 4xx auth, validation, or not-found errors. Null if unclear.
6. **retry_after_seconds**: Extract from "Retry-After" header if provided in [HEADERS], or from body fields like "retry_after", "retryAfter", "retry_in". Null if not present.
7. **rate_limit_remaining**: Extract from rate limit headers or body fields indicating quota remaining. Null if not present.
8. **rate_limit_reset_epoch**: Unix timestamp (seconds) when the rate limit resets. Extract from headers or body. Null if not present.
9. **documentation_url**: Extract any URL pointing to error documentation. Look for fields named "docs", "documentation_url", "help", "more_info", or "type" when it contains a URI.
10. **request_id**: Extract the request or trace ID for correlation. Look in fields named "request_id", "requestId", "trace_id", "x-request-id", or similar.
11. **raw_body_preserved**: Always include the original raw body as a string, truncated to 4000 characters if longer.
12. **field_confidence**: For each extracted field, assign a confidence score: 1.0 = exact field name match in structured JSON; 0.7-0.9 = extracted via pattern matching or inference; 0.3-0.6 = guessed from context; 0.0 = field is null because no information was available.
13. **parsing_notes**: If the body was HTML, truncated, empty, or in an unexpected format, note it here. Otherwise null.

## CONSTRAINTS
- Do not hallucinate error codes or messages.
- If the body is empty or only whitespace, set all extractable fields to null with confidence 0.0 and note "empty_body" in parsing_notes.
- If the body is HTML, attempt to extract visible error text but set error_code to null with confidence 0.0.
- Preserve the original error string exactly in error_message; do not rewrite or summarize.
- Output only the JSON object. No markdown, no commentary.

## EXAMPLES
[EXAMPLES]

Adaptation guidance: Replace [RAW_ERROR_BODY] with the actual error response string from your HTTP client. [HTTP_STATUS_CODE] should be the integer status code. [CONTENT_TYPE] should be the Content-Type header value (e.g., application/json, text/html). [SERVICE_NAME] is a label for the originating API. The [EXAMPLES] placeholder should be replaced with 2-4 few-shot examples showing correct extraction from your most common error formats—include at least one malformed body and one empty body example. If you have access to response headers, add a [HEADERS] placeholder and include the relevant rate-limit and retry headers. For production use, wrap this prompt in a validation layer that checks the output JSON against the schema before passing it downstream.

What to do next: After pasting this template into your prompt layer, run it against a golden set of 20-30 known error responses from each API you integrate with. Compare the extracted fields against manually labeled ground truth. Pay special attention to field_confidence scores—if confidence drops below 0.7 on critical fields like error_code or retryable, add more examples or refine the extraction rules. Do not ship this prompt without eval coverage for empty bodies, HTML error pages, truncated responses, and nested error arrays.

The Structured Error Body Extraction Prompt is designed to be called as a post-processing step after your application receives a non-2xx HTTP response from an upstream API. Instead of logging the raw, potentially malformed payload, you route the response body and the expected schema into this prompt to produce a clean, normalized NormalizedError object. This extraction layer should sit between your HTTP client's error handler and your application's logging, alerting, and retry logic. The prompt is stateless and idempotent, making it safe to call multiple times for the same error payload without side effects.

In a typical implementation, wrap the LLM call in a function like extractStructuredError(rawBody: string, statusCode: int, expectedSchema: string) -> NormalizedError. The function should enforce a strict timeout (e.g., 2 seconds) since error extraction is on the critical path for error handling. On failure—whether a timeout, a malformed model response, or a validation error—fall back to a minimal NormalizedError that preserves the raw body in an unparsed_raw field and sets extraction_confidence to 0.0. Log this fallback event as a warning so your team can investigate extraction gaps. For high-throughput systems, consider batching extraction requests or using a smaller, faster model for this task, as the schema is well-defined and the input is bounded.

Before the extracted error reaches any downstream system, validate the output against your NormalizedError schema. Check that error_code is a non-empty string, http_status matches the actual status code received, and remediation_hints is a list of actionable strings. If the field_confidence map shows any required field below your threshold (e.g., 0.7), flag the extraction for human review or route it to a secondary extraction prompt with more explicit instructions. For regulated environments, always log the raw response body alongside the normalized output to maintain an audit trail. Never suppress the original error—the normalized version is an augmentation, not a replacement.