HTTP Status Code Mapping Prompt for API Errors

This prompt is designed for backend engineers and API designers who need to standardize how internal error conditions map to HTTP status codes. The core job-to-be-done is producing a decision table that assigns each internal error condition—such as 'user not found', 'rate limit exceeded', or 'database timeout'—to the correct HTTP status code with explicit RFC 9110 rationale. The ideal user already has a catalog of internal error conditions and needs a systematic, standards-based mapping that can be reviewed, versioned, and enforced across endpoint families. This is not a prompt for generating error response bodies, user-facing messages, or remediation steps; those tasks require separate, specialized prompts that assume the status code mapping is already decided.

Use this prompt when you are standardizing error responses across multiple services, auditing existing status code usage for RFC compliance, or onboarding a new endpoint family that must align with organizational error conventions. The prompt requires a structured input: a list of internal error conditions, each with a unique identifier and a short description of the failure scenario. Optionally, you can provide the HTTP method and resource type to improve the mapping accuracy for overload and concurrency edge cases. The output is a decision table with columns for the internal error condition, assigned HTTP status code, RFC 9110 section reference, rationale, and any consistency flags where the mapping conflicts with other endpoint families. The prompt includes explicit guidance for distinguishing between 429 (rate limit from the client) and 503 (server overload), as well as between 409 (state conflict) and 422 (semantic error), which are common sources of inconsistency in production APIs.

Do not use this prompt when you lack a defined set of internal error conditions, when you need to generate the error body schemas or user-facing messages, or when you are designing the error taxonomy itself. For those tasks, use the sibling prompts in the Error Code and Troubleshooting Reference content group, such as the Error Code Taxonomy Builder or the Structured Error Body Extraction prompt. Also avoid this prompt if your API uses non-standard status codes or if you are mapping errors for a protocol other than HTTP. The prompt assumes RFC 9110 compliance as a baseline; if your organization has intentionally diverged from RFC standards, you must supply those divergence rules as part of the [CONSTRAINTS] input. After running this prompt, always review the output for consistency with your existing API documentation and run the Error Code Consistency Audit Prompt to catch cross-service misalignments before publishing.

This prompt template is the core engine for standardizing your API's error responses. It takes a list of internal error conditions—such as 'database connection pool exhausted' or 'request payload exceeds size limit'—and maps each one to the most appropriate HTTP status code. The model is instructed to produce a structured decision table, justify each mapping against relevant RFCs (like RFC 7231 and RFC 6585), and flag any ambiguous or overloaded scenarios where multiple codes could apply. Use this as the starting point for building a consistent error taxonomy across all your service endpoints.

codeCopy
You are an expert in HTTP semantics and RESTful API design. Your task is to map a list of internal error conditions to standard HTTP status codes.

## INPUT
[ERROR_CONDITIONS]

## CONSTRAINTS
- Map each condition to the single most appropriate HTTP status code from RFC 7231, RFC 6585, or RFC 7540.
- For each mapping, provide a concise rationale that references the specific RFC section or standard industry practice.
- If a condition is ambiguous (e.g., overload could be 429, 503, or 502 depending on the cause), flag it and explain the decision criteria.
- Do not invent custom status codes. Use only registered IANA HTTP status codes.
- Consider the client's ability to react: 4xx for client-fixable errors, 5xx for server-side or operational issues.

## OUTPUT_SCHEMA
Return a JSON object with a single key "mappings" containing an array of objects. Each object must have the following fields:
- "internal_condition": string (the exact condition from the input)
- "http_status_code": integer
- "http_reason_phrase": string
- "rationale": string (RFC reference and reasoning)
- "client_action": string (what the client should do, e.g., retry, modify request, contact support)
- "ambiguity_flag": boolean (true if multiple codes could apply)
- "ambiguity_notes": string or null (explain the tie-breaker if ambiguity_flag is true)

## EXAMPLES
Input: "Request body is not valid JSON"
Output:
{
  "internal_condition": "Request body is not valid JSON",
  "http_status_code": 400,
  "http_reason_phrase": "Bad Request",
  "rationale": "Per RFC 7231 Section 6.5.1, 400 Bad Request indicates the server cannot process the request due to a client error, such as malformed syntax.",
  "client_action": "Validate JSON syntax before resending.",
  "ambiguity_flag": false,
  "ambiguity_notes": null
}

## RISK_LEVEL
Low. Output is advisory and used for documentation and server configuration. Human review is required before implementing status code changes in production to prevent breaking client error-handling logic.

After pasting this template into your AI harness, replace the [ERROR_CONDITIONS] placeholder with your actual list of internal error strings. For best results, provide conditions that describe the root cause, not just the symptom (e.g., 'upstream auth service unreachable' instead of 'auth failed'). The output JSON can be directly consumed by a script that generates your API reference docs or configures your API gateway's error mapping rules. Always run the output through a validation step that checks every status code against the IANA registry and confirms that no two distinct internal conditions map to the same code without an explicit, documented reason.

This prompt is designed to be called programmatically as part of an API standardization pipeline or a code review assistant. The primary integration point is a backend service that collects internal error conditions—either from source code annotations, structured logs, or an existing error catalog—and passes them to the model in the [ERROR_CONDITIONS] placeholder. The output is a structured decision table that maps each condition to an HTTP status code with rationale. Because the output must be machine-readable for downstream tooling, you should enforce a strict JSON schema in the [OUTPUT_SCHEMA] block and validate the response before accepting it.

Implement a validation layer that checks every returned mapping against RFC 7231 and RFC 6585 semantics. For each row, confirm that the http_status_code is a valid integer in the 4xx or 5xx range, that the rationale field references the specific RFC section or established convention, and that edge cases like 429 vs 503 are explicitly justified with the overload scenario described in the input. If validation fails, retry the prompt once with the validation errors appended to the [CONSTRAINTS] block. Log both the initial and retry responses for auditability. For high-risk API surfaces—such as payment endpoints or authentication flows—route the final decision table to a human reviewer through a pull request or approval queue before merging into the API specification.

Model choice matters here: use a model with strong instruction-following and structured output capabilities, such as GPT-4o or Claude 3.5 Sonnet, with response_format set to json_object and a low temperature (0.0–0.2) to maximize consistency. If you are processing a large error catalog, batch the conditions into groups of 20–30 to stay within reliable context windows and avoid truncation. Store the output in a version-controlled artifact (e.g., a JSON file in the API spec repository) so that changes are diffable and reviewable. Avoid using this prompt for real-time request handling; it is a design-time tool, not a runtime classifier.