OAuth 2.0 Error Response Reference Generation Prompt

This prompt is built for support engineers and API documentation teams who need to produce a structured, actionable catalog of OAuth 2.0 error codes. The primary job-to-be-done is converting a list of error codes from your authorization server—or the standard RFC 6749 registry—into a complete reference that maps each error (such as invalid_grant, invalid_client, or unauthorized_client) to its correct HTTP status code, a plain-language description of common causes, and concrete resolution steps for the developer consuming your API. The ideal user is someone who already understands OAuth 2.0 grant flows but needs to eliminate ambiguity and inconsistency from the error documentation that developers rely on during integration and debugging.

Use this prompt when you are building a new error reference from scratch, auditing an existing error page against the RFC-defined error registry, or standardizing error documentation across multiple services that share an authorization server. The prompt requires you to provide a list of error codes in the [ERROR_CODES] variable, and it will produce a completeness check against the standard OAuth 2.0 error registry defined in RFC 6749 Section 5.2. You can also supply custom, proprietary error codes through the [CUSTOM_ERRORS] variable, but you must include their definitions, HTTP status mappings, and resolution guidance—the prompt will not invent plausible causes for undocumented errors. The output is designed to be copied directly into a developer portal or API reference page, with consistent formatting and no placeholder text.

Do not use this prompt for generating general API error documentation outside the OAuth 2.0 framework. It is specifically tuned to the OAuth error registry and will not produce useful results for GraphQL errors, database constraint violations, or HTTP 5xx infrastructure errors. Do not use it to document non-standard error codes without providing their definitions in the [CUSTOM_ERRORS] variable—the prompt will flag missing definitions rather than hallucinate them. If your authorization server returns errors that violate the RFC's expected HTTP status code mappings, supply those overrides in the [STATUS_OVERRIDES] variable so the output reflects reality rather than the specification. After generating the reference, run the included eval checks to verify that every error code in your system appears in the output and that no RFC-defined error is missing without an explicit exclusion note.

This prompt template is designed to produce a comprehensive, structured error catalog for OAuth 2.0 flows. You provide a list of error codes (e.g., invalid_grant, invalid_client) and any relevant context about your authorization server's specific behavior. The model will generate a reference table mapping each error to its HTTP status code, a description, common causes, and actionable resolution steps. The prompt includes strict instructions to ground its output in RFC 6749 and RFC 6750, ensuring accuracy and completeness.

textCopy
You are an expert in OAuth 2.0 and API security documentation. Your task is to generate a structured error response reference from a provided list of OAuth 2.0 error codes.

**Input Error Codes:**
[ERROR_CODE_LIST]

**Authorization Server Context (Optional):**
[CONTEXT]

**Instructions:**
1.  For each error code in the [ERROR_CODE_LIST], generate a reference entry.
2.  Ground every entry in the OAuth 2.0 specifications (RFC 6749, RFC 6750). Do not invent error codes or behaviors.
3.  If an error code is not defined in the core RFCs but is common in practice (e.g., from OpenID Connect), note this in the entry.
4.  The output must be a single, valid JSON object conforming to the [OUTPUT_SCHEMA].
5.  If the [CONTEXT] is provided, use it to tailor the 'common_causes' and 'resolution_steps' to the specific authorization server. If not provided, use generic but technically accurate causes and steps.
6.  Perform a completeness check against the standard OAuth 2.0 error registry before finalizing. If a standard error code is missing from the [ERROR_CODE_LIST], add it to the output with a note that it was missing from the input.

**Output Schema:**
```json
{
  "error_reference": [
    {
      "error_code": "string",
      "http_status_code": 400,
      "description": "A clear, one-sentence description of the error.",
      "common_causes": [
        "A specific, actionable cause."
      ],
      "resolution_steps": [
        "A concrete step a developer can take to resolve the issue."
      ],
      "rfc_section": "RFC 6749 Section 5.2"
    }
  ],
  "completeness_notes": [
    "A note about any standard error codes that were missing from the input and added to the reference."
  ]
}

Constraints:

• Do not include any text outside the JSON object.
• Ensure all JSON fields are present for every error code.
• The http_status_code must be a valid HTTP status code number.
• Resolution steps must be developer-focused and avoid vague advice like "check your configuration."

To adapt this template, replace the [ERROR_CODE_LIST] placeholder with a comma-separated list or JSON array of the error codes you need to document. The [CONTEXT] placeholder is optional but highly recommended; use it to describe your specific authorization server implementation, such as custom error responses, unique token endpoint behaviors, or known client misconfigurations. After generating the output, you should validate the JSON structure and verify the RFC citations against the actual specification documents. For high-stakes documentation, a human security engineer must review the generated reference before publication.

This prompt is designed to be called programmatically as part of a documentation generation or audit workflow, not as a one-off chat interaction. The typical integration pattern involves feeding a list of OAuth error codes—sourced from your API gateway logs, OpenAPI specification, or an RFC registry—into the prompt and expecting a structured JSON or Markdown table output that can be directly ingested by your documentation platform. Because the output is intended for a troubleshooting reference that developers will rely on during incidents, the harness must enforce schema compliance, completeness against the known error registry, and grounding in your specific API's behavior before publication.

Wire the prompt into a pipeline that first collects all error codes your authorization server actually returns. This can be done by scanning your source code for error response constructors, scraping your API gateway's error log schemas, or extracting them from an OpenAPI spec. Pass this list as the [ERROR_CODES] input, along with your specific HTTP status code mappings in [HTTP_MAPPINGS] and any internal troubleshooting runbook links in [RESOLUTION_LINKS]. The model call should be configured with response_format set to a strict JSON schema that matches your documentation site's frontmatter structure. After generation, run a validation step that checks: (1) every error code in your source registry appears in the output, (2) no hallucinated error codes were added, (3) all HTTP status codes match your gateway's actual behavior, and (4) every entry includes a non-empty cause and resolution field. If validation fails, use a retry loop with the specific failures injected back into the [CONSTRAINTS] field, such as "The previous output was missing entries for 'invalid_grant' and 'unauthorized_client'. Regenerate the full catalog including these codes."

For high-stakes documentation like auth error references, do not publish the model's output directly. Route all generated content through a human review queue where a security engineer or API product manager can verify that resolution steps do not inadvertently recommend insecure practices—such as suggesting a client secret be logged or exposing internal error details that could aid an attacker. Log every generation attempt, the validation results, and the reviewer's decision for auditability. Choose a model with strong instruction-following and low hallucination rates for structured data tasks; GPT-4o or Claude 3.5 Sonnet are appropriate starting points. Avoid using smaller open-weight models for this task unless you have a robust fine-tuning dataset of your specific error catalog, as they are more prone to inventing plausible but incorrect error codes or HTTP status mappings.