Error Code Explanation Prompt for Developer Docs

This prompt is designed for API and platform engineering teams who need to transform raw internal documentation, error logs, or specification fragments into structured, developer-facing error code references. The primary job-to-be-done is automating the creation of consistent, actionable troubleshooting entries that include root causes, concrete resolution steps, and copy-pasteable code examples. The ideal user is a technical writer, developer advocate, or backend engineer responsible for maintaining a public or internal developer portal where accuracy and testability are non-negotiable.

Use this prompt when you have a source of truth—such as a markdown file, an OpenAPI specification, or a runbook—that describes error conditions but lacks a uniform structure. It is appropriate for generating net-new documentation or standardizing a backlog of inconsistent error entries. The prompt requires a specific error code and its raw context as input. It is not a general-purpose debugging assistant; do not use it to diagnose live production incidents or to generate explanations from a model's parametric knowledge without grounding evidence. The output is a structured object designed to be validated programmatically before it reaches a developer's screen.

Avoid this prompt when the source material is ambiguous, contradictory, or purely anecdotal. If the input context does not contain enough information to derive a cause and a testable resolution, the prompt will either fabricate plausible-sounding steps or produce a low-confidence output that erodes developer trust. For high-risk APIs where an incorrect resolution could lead to data loss, security gaps, or billing errors, always route the generated output through a human SME review step and an automated test that executes the provided code example against a sandbox environment. The next section provides the exact template and placeholders you need to wire this into your documentation pipeline.

This template is designed to produce a complete, developer-facing error code reference entry. It forces the model to extract the error code, a human-readable message, probable causes, concrete resolution steps, and a minimal code example—all grounded in the provided documentation context. Use it when you need to scale error documentation across hundreds of endpoints or when onboarding new API surfaces.

codeCopy
You are a technical writer for a developer documentation team. Your task is to generate a structured error code explanation from the provided API documentation context.

[CONTEXT]
The following is the relevant API documentation:
---
[DOCUMENTATION]
---

[INPUT]
Error Code to explain: [ERROR_CODE]

[OUTPUT_SCHEMA]
You must respond with a valid JSON object matching this exact schema:
{
  "error_code": "string",
  "http_status": "integer",
  "message": "string (the exact error message string returned by the API)",
  "severity": "string (enum: 'critical', 'error', 'warning')",
  "description": "string (a plain-language explanation of what the error means)",
  "likely_causes": ["string (a specific, actionable cause)"],
  "resolution_steps": ["string (an ordered, numbered step the developer can take)"],
  "code_example": {
    "language": "string (e.g., 'curl', 'python', 'javascript')",
    "code": "string (a minimal code snippet that triggers the error)",
    "fix": "string (a minimal code snippet showing the corrected request)"
  },
  "related_error_codes": ["string"],
  "source_reference": "string (the section or page in the documentation where this error is defined)"
}

[CONSTRAINTS]
- If the [DOCUMENTATION] does not contain information about [ERROR_CODE], set all fields to null and set "description" to "Error code not found in provided documentation."
- "resolution_steps" must be ordered, specific, and testable. Do not include generic advice like "check your code."
- The "code_example.fix" must be a direct correction of "code_example.code".
- Do not invent causes or resolutions not supported by the [DOCUMENTATION].
- If the documentation implies multiple causes, list the most common one first.

[EXAMPLES]
Input: Error Code: "RATE_LIMITED"
Output:
{
  "error_code": "RATE_LIMITED",
  "http_status": 429,
  "message": "You have exceeded the rate limit. Retry after 60 seconds.",
  "severity": "error",
  "description": "The client has sent too many requests in a given amount of time.",
  "likely_causes": [
    "Client is not implementing exponential backoff.",
    "Client is making requests in a tight loop without checking Retry-After headers."
  ],
  "resolution_steps": [
    "Check the 'Retry-After' header in the response for the number of seconds to wait.",
    "Implement exponential backoff with jitter in your request client.",
    "If you have a legitimate need for a higher limit, contact support to request a rate limit increase."
  ],
  "code_example": {
    "language": "curl",
    "code": "for i in {1..100}; do curl -X GET 'https://api.example.com/v1/resource'; done",
    "fix": "# Use a library that respects Retry-After headers or implement a sleep.\nsleep 60"
  },
  "related_error_codes": ["SERVICE_UNAVAILABLE"],
  "source_reference": "API Reference > Errors > Rate Limiting"
}

[RISK_LEVEL]
High. Inaccurate resolution steps can lead to developer frustration and production incidents. Always validate against the source documentation.

To adapt this template, replace the [DOCUMENTATION] placeholder with the relevant markdown or text chunk from your API spec. For batch processing, iterate over a list of [ERROR_CODE] values. The strict JSON schema and the explicit instruction to return null fields for missing information are critical for downstream automation—they prevent the model from hallucinating plausible-sounding but incorrect error details. Before deploying, run this prompt against a golden set of 20 known error codes and validate that source_reference correctly points back to the original documentation section.

This prompt is designed to be called programmatically as part of a documentation generation pipeline, not as a one-off chat interaction. The typical integration point is a backend service that retrieves raw documentation chunks via search or a direct API lookup, assembles the prompt with the error code and surrounding context, calls a language model, and then validates the structured output before publishing it to a developer portal or API reference site. The output schema is the contract: every field must be present, correctly typed, and non-hallucinatory before the explanation reaches a developer.

Start by wrapping the prompt in a function that accepts error_code, source_docs, and optional platform_context as parameters. The function should construct the prompt string, substituting these values into the [ERROR_CODE], [RETRIEVED_CONTEXT], and [PLATFORM_CONTEXT] placeholders. Choose a model that reliably produces structured JSON output—GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro with response_format set to JSON mode are good starting points. Set temperature to 0 or a very low value (0.1–0.2) to maximize schema consistency. After receiving the model response, run a strict JSON schema validator against the expected structure: error_code (string, must match input), title (string, non-empty), description (string, non-empty), likely_causes (array of objects with cause and evidence fields), resolution_steps (array of objects with step_number, action, and code_example fields), and related_errors (array of strings). Reject any response that fails validation and retry with a repair prompt that includes the validation error message and the malformed JSON.

For high-stakes developer documentation—especially for paid APIs, security-related errors, or compliance-bound platforms—insert a human review step before publication. After validation passes, route the generated explanation to a review queue where a technical writer or engineer can confirm cause accuracy, test the resolution steps, and verify that no error variants are missing. Log every generation attempt, including the prompt version, model used, raw output, validation result, and reviewer decision. This audit trail is essential for debugging prompt drift and for demonstrating due diligence if an incorrect error explanation causes customer impact. Avoid publishing generated explanations directly to production without either automated eval gates (cause accuracy, resolution testability) or human approval, and never use this prompt for error codes where the source documentation is incomplete or ambiguous—the model will fabricate plausible but incorrect causes.