Error Code Taxonomy Builder Prompt

This prompt is designed for API governance teams and platform architects who need to standardize error codes across multiple services. The primary job-to-be-done is producing a hierarchical error taxonomy with domain, category, and specific error codes that ensures consistent naming and non-overlapping semantics. Use this prompt when you are consolidating error responses from multiple teams, migrating from legacy error codes, or establishing a new API error standard. The ideal user is a technical lead or architect who has access to existing error conditions, service boundaries, and domain contexts, and who can make binding decisions about taxonomy structure.

The output is a structured taxonomy document, not a runbook or remediation guide. This prompt assumes you have a list of existing error conditions, service boundaries, and domain contexts to feed in as input. It does not replace human review for semantic correctness or business logic alignment. Before using this prompt, gather your current error codes, service maps, and any existing documentation on error semantics. The prompt works best when you provide concrete examples of current error codes and the services that produce them, along with any known overlaps or inconsistencies you want resolved.

Do not use this prompt when you need a complete error catalog with HTTP status codes, response bodies, and resolution steps—that requires the Error Code Catalog Generation Prompt instead. Avoid this prompt if you are looking for a one-time fix for a single service's errors; it is designed for cross-service standardization efforts. After generating the taxonomy, you should review the output for semantic correctness, ensure no business-critical error conditions were omitted, and validate that the hierarchy aligns with your API versioning and deprecation policies before adopting it as a standard.

This template is designed for API governance teams that need to standardize error codes across multiple services. It instructs the model to produce a structured taxonomy organized by domain, category, and specific error code, ensuring consistent naming conventions and non-overlapping semantics. The prompt expects you to provide your existing error codes, service boundaries, and any legacy mappings as input. The output is a complete taxonomy document that can be fed directly into your API standards repository or used as the foundation for automated validation tooling.

textCopy
You are an API governance specialist tasked with building a hierarchical error code taxonomy for a multi-service platform. Your goal is to produce a consistent, non-overlapping error code catalog that every service can adopt.

## INPUT
[EXISTING_ERROR_CODES]
[SERVICE_BOUNDARIES]
[LEGACY_CODE_MAPPINGS]

## TAXONOMY STRUCTURE
Organize every error code into a three-level hierarchy:
1. **Domain**: The business or technical area (e.g., AUTH, BILLING, STORAGE, RATE_LIMITING).
2. **Category**: The error class within the domain (e.g., AUTH/CREDENTIALS, AUTH/PERMISSIONS, BILLING/INVOICE).
3. **Specific Code**: The unique error identifier (e.g., AUTH_CREDENTIALS_EXPIRED, BILLING_INVOICE_NOT_FOUND).

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "taxonomy_version": "string",
  "domains": [
    {
      "domain": "string",
      "description": "string",
      "categories": [
        {
          "category": "string",
          "description": "string",
          "error_codes": [
            {
              "code": "string",
              "http_status": 400,
              "severity": "CRITICAL|HIGH|MEDIUM|LOW",
              "description": "string",
              "retryable": true,
              "requires_human_intervention": false,
              "legacy_equivalents": ["string"],
              "migration_notes": "string"
            }
          ]
        }
      ]
    }
  ],
  "cross_service_conflicts": [
    {
      "conflict_type": "DUPLICATE_SEMANTICS|NAMING_COLLISION|STATUS_MISMATCH",
      "codes_involved": ["string"],
      "resolution": "string"
    }
  ],
  "migration_map": [
    {
      "legacy_code": "string",
      "new_code": "string",
      "breaking_change": true,
      "consumer_impact": "string"
    }
  ]
}

## CONSTRAINTS
- Every error code must be unique across all domains and categories.
- HTTP status codes must align with RFC 9110 semantics.
- No two error codes may describe the same condition with different names.
- Legacy equivalents must be exhaustive if provided in [LEGACY_CODE_MAPPINGS].
- If a legacy code maps to multiple new codes, flag it in migration_notes.
- Severity must be assigned based on consumer impact, not implementation difficulty.
- Retryable must be true only for transient conditions where a retry can succeed without state change.

## CROSS-SERVICE VALIDATION
After generating the taxonomy, scan for:
1. Duplicate semantics: two codes from different services describing the same error.
2. Naming collisions: identical code strings with different meanings.
3. HTTP status mismatches: similar errors returning inconsistent status codes.
Document every conflict in the cross_service_conflicts array with a concrete resolution.

## OUTPUT INSTRUCTIONS
Return only the JSON object. Do not include explanations, markdown fences, or commentary outside the JSON structure.

Before pasting this template into your AI system, replace the three square-bracket placeholders with your actual data. [EXISTING_ERROR_CODES] should contain a structured list of every error code currently in use across your services, including their HTTP status codes and descriptions. [SERVICE_BOUNDARIES] should define which service owns which domain or category, preventing two teams from accidentally claiming the same error space. [LEGACY_CODE_MAPPINGS] is optional but critical if you are migrating from an older error code scheme—include every old-to-new mapping you already know. If you have no legacy codes, replace the placeholder with an empty array [].

After running the prompt, validate the output against your API contracts before adopting the taxonomy. Check that every existing error code appears in the migration map, that no two services claim the same code, and that HTTP status codes match what your gateways actually return. For high-risk domains like billing or authentication, have a senior engineer review the severity and retryability assignments before publishing the taxonomy to your developer portal. If the model flags cross-service conflicts you were unaware of, treat those as action items for your next API governance review.

The Error Code Taxonomy Builder prompt is designed to be a deterministic governance tool, not a conversational assistant. It should be integrated into a CI/CD or API design review pipeline where it receives a structured input payload of existing error codes, domain boundaries, and legacy mappings. The prompt's output is a machine-readable taxonomy object that downstream systems—such as API gateways, documentation generators, and monitoring dashboards—will consume. Because the output directly shapes error contracts that clients depend on, the implementation harness must enforce strict validation before the taxonomy is accepted.

Wire the prompt into an application as a gated transformation step. The application should: (1) assemble the input context from a service registry, OpenAPI specs, or a configuration repository; (2) call the LLM with the prompt template, setting temperature=0 and using a model with strong JSON mode support (e.g., GPT-4o, Claude 3.5 Sonnet); (3) validate the output against a JSON Schema that checks for unique error codes, non-overlapping semantics, required fields (domain, category, code, http_status, description), and valid migration mappings from legacy codes; (4) on validation failure, retry once with the validation errors injected into the [CONSTRAINTS] block, then escalate to a human reviewer if the second attempt fails; (5) log the input, output, model version, and validation result for auditability. Do not auto-merge the taxonomy into production error catalogs without human approval when the change set includes breaking changes to existing error codes or HTTP status codes.

For cross-service consistency validation, implement a post-generation diff step that compares the new taxonomy against the existing taxonomy from other services in the same domain. Flag any error code that duplicates an existing code's semantics under a different name, or any HTTP status code assignment that conflicts with the organization's status code conventions. The [CONSTRAINTS] placeholder in the prompt template should be populated with these organization-specific rules (e.g., 'all authentication errors must use 401 or 403, never 400'). For legacy migration mappings, add a drift detection check that verifies every legacy code in the input appears in the output's legacy_mapping field, and that no legacy code is mapped to multiple new codes without an explicit disambiguation rule. If the prompt is used in a regulated industry, require a human governance board sign-off on the final taxonomy before it is published to API consumers.