Error Object Standardization Prompt for API Responses

This prompt is for API developers and platform engineers who need to enforce a consistent error object structure across multiple services, teams, or code-generated endpoints. The job-to-be-done is turning unstructured error descriptions, exception traces, or legacy error formats into a single, validated error envelope that every client can parse reliably. Use it when you are building or refactoring an API gateway, standardizing error responses from microservices, or generating OpenAPI error schemas that must match a company-wide contract. The ideal user already has an error code registry, a defined envelope structure, and a list of required fields such as code, message, details, and traceId.

You should not use this prompt when the error taxonomy itself is undefined or when the team has not agreed on error codes, severity levels, or HTTP status mappings. This prompt standardizes the shape of error objects, not the business logic that decides which error to return. It also should not replace a proper exception handler in application code; the prompt is a design-time and documentation-time tool, not a runtime error serializer. If you need to normalize errors from third-party services whose schemas you do not control, pair this prompt with a data extraction step that maps foreign error fields into your canonical schema first.

Before using this prompt, gather your error code registry as a controlled vocabulary, your target JSON Schema for the error envelope, and at least five examples of errors from different services that currently break consistency. The prompt works best when you provide concrete examples of both well-formed and malformed error objects so the model learns the boundary between acceptable and unacceptable outputs. If your error envelope includes optional fields like suggestions, links, or retryAfter, specify their nullability rules explicitly in the [CONSTRAINTS] placeholder. For high-risk domains such as payments or healthcare, always require human review of the generated schema and error code mappings before they are published to API documentation or client SDKs.

This prompt template is designed to be copied directly into your AI harness, IDE, or prompt management system. It accepts raw error context—such as exception messages, HTTP status codes, internal error codes, and stack traces—and produces a consistent, validated error object that matches your organization's API envelope contract. The template uses square-bracket placeholders for all variable inputs, making it safe to store in configuration files, prompt libraries, and version control without accidental token interpolation.

textCopy
You are an API error standardization engine. Your job is to convert raw error information into a consistent error object that conforms to the organization's API error envelope specification.

## INPUT
Raw error data:
[RAW_ERROR_DATA]

## CONTEXT
- API version: [API_VERSION]
- Service name: [SERVICE_NAME]
- Environment: [ENVIRONMENT]
- Error code registry (valid error codes and their canonical descriptions):
[ERROR_CODE_REGISTRY]
- Correlation ID (if available): [CORRELATION_ID]
- Request ID (if available): [REQUEST_ID]

## OUTPUT SCHEMA
Produce a JSON object matching this exact structure:
{
  "error": {
    "code": "string (must match a code from the error code registry)",
    "message": "string (human-readable, no internal implementation details exposed)",
    "details": [
      {
        "field": "string (path to the field that caused the error, or null if not applicable)",
        "reason": "string (specific reason for this detail entry)",
        "value": "any (the problematic value, if safe to expose, or null)"
      }
    ],
    "trace_id": "string (use the provided correlation ID or request ID, or generate a new UUID v4 if neither is available)",
    "timestamp": "string (ISO 8601 UTC timestamp of when this error object was generated)",
    "documentation_url": "string (link to the relevant error documentation for this code, or null if not available)"
  }
}

## CONSTRAINTS
1. The `code` field MUST be selected from the provided error code registry. If no matching code exists, use "INTERNAL_ERROR" and note the mismatch in the `details` array.
2. The `message` field MUST NOT expose stack traces, database queries, file paths, internal hostnames, or any implementation details. Rewrite technical messages into user-safe descriptions.
3. The `details` array MUST contain at least one entry when the error relates to a specific input field or parameter. It MAY be empty for general errors.
4. The `trace_id` MUST be a valid UUID v4 string. Prefer the provided correlation ID if present, then the request ID, then generate a new one.
5. The `timestamp` MUST be the current time in ISO 8601 UTC format (e.g., "2025-01-15T14:30:00Z").
6. If the raw error data contains sensitive information (PII, credentials, tokens), redact it and add a detail entry noting that sensitive data was removed.
7. Do NOT invent error codes. If the registry does not contain an appropriate code, use "INTERNAL_ERROR" and add a detail entry explaining what code would have been ideal.

## EXAMPLES

Example 1:
Input: HTTP 422, field "email" failed format validation
Output:
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid fields. Please correct the errors and try again.",
    "details": [
      {
        "field": "email",
        "reason": "Email address format is invalid",
        "value": "user@"
      }
    ],
    "trace_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-01-15T14:30:00Z",
    "documentation_url": "https://api.example.com/docs/errors/VALIDATION_ERROR"
  }
}

Example 2:
Input: Database connection timeout, internal stack trace available
Output:
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The service is temporarily unavailable. Please try again later.",
    "details": [],
    "trace_id": "550e8400-e29b-41d4-a716-446655440001",
    "timestamp": "2025-01-15T14:31:00Z",
    "documentation_url": "https://api.example.com/docs/errors/SERVICE_UNAVAILABLE"
  }
}

## RISK_LEVEL
[HIGH] This prompt handles error data that may contain sensitive information. Always validate the output before returning it to API consumers. Ensure stack traces, internal paths, and credentials are never exposed in the `message` or `details` fields.

## INSTRUCTIONS
1. Parse the raw error data to identify the error type, affected fields, and severity.
2. Match the error to the most specific code in the error code registry.
3. Construct the error object following the output schema exactly.
4. Sanitize all message content to remove implementation details.
5. Output ONLY the JSON object. Do not include any explanatory text, markdown fences, or commentary.

To adapt this template for your organization, replace the error code registry with your actual canonical error codes and their descriptions. If your API envelope uses a different structure—such as wrapping errors in a data field or using a different timestamp format—modify the output schema accordingly. The constraint to never expose implementation details is non-negotiable for production use; always run the output through an automated sanitization check before returning it to API consumers. For high-risk environments, add a human review step when the model selects INTERNAL_ERROR as the code, since this indicates the error code registry may need expansion.

This prompt is designed to sit inside an API gateway, sidecar, or middleware layer that intercepts error responses from multiple backend services and normalizes them before they reach the client. The typical integration point is a post-response hook: after a backend returns a non-2xx status code, the raw error payload is extracted, passed through this prompt as the [INPUT], and the standardized output replaces the original error body before the response is sent upstream. You should not use this prompt on successful responses or as a real-time transformation on every request—it is specifically for error normalization and adds latency that is only justified when an error has already occurred.

Wire the prompt into a lightweight service function that receives the raw error body, the HTTP status code, the service name, and a trace ID. Construct the [CONTEXT] placeholder by injecting your organization's error code registry as a JSON object mapping service domains to allowed error codes, plus the current service's domain identifier. The [OUTPUT_SCHEMA] should be a JSON Schema that defines your standard error envelope: required fields typically include error.code, error.message, error.domain, error.timestamp, and error.trace_id. Add a details array for field-level or validation errors. Before the model call, validate that the raw error body is parseable—if it's already in your standard format, skip the prompt to save cost and latency. After the model returns, run the output through a JSON Schema validator. If validation fails, retry once with the validation error message appended to [CONSTRAINTS]. If the second attempt also fails, log the failure, attach the raw error to a _raw field in a fallback envelope, and alert the on-call channel. This prompt works well with fast, cost-effective models like GPT-4o-mini or Claude Haiku for most error shapes; reserve larger models only for errors with complex nested structures or multi-service cascades.

For observability, log every invocation with the input service domain, the original error code, the standardized error code, validation pass/fail, retry count, and latency. This data will help you identify services that consistently produce non-standard errors and may need their own error handling fixed at the source. Avoid using this prompt for errors that contain PII or sensitive data in their messages—redact those fields before they reach the model, or route those errors to a human review queue. If your error code registry changes, update the [CONTEXT] injection immediately; stale registries will cause the model to reject valid codes or accept deprecated ones. The prompt is not a substitute for fixing broken error handling in upstream services—use the observability data to drive those fixes while the prompt provides a safety net.