Rate Limiting Error Message Design Prompt

API platform engineers should run this prompt during design review, gateway configuration testing, or before publishing a new rate limit tier. The job-to-be-done is evaluating whether a concrete 429 Too Many Requests response payload meets HTTP standards and developer expectations. The ideal user is an engineer who already has a response body and headers in hand—captured from a staging gateway, a mock server, or an integration test—and needs a structured quality assessment before that response reaches external developers. The required context includes the full response payload, the HTTP headers (especially Retry-After and any custom rate limit headers), and the API's documented rate limit policy for comparison.

This prompt is not for generating rate limit policies, configuring gateway rules, or designing quota systems from scratch. It assumes the policy exists and the response is already being produced. Do not use this prompt when you need to decide what the rate limit should be, how to partition quotas across tiers, or which algorithm to implement at the gateway level. It is also not a substitute for integration tests that verify the gateway actually triggers a 429 under load—this prompt evaluates the quality of the error message, not the correctness of the rate limiting logic itself.

The prompt produces a structured developer experience score and a prioritized list of missing or suboptimal elements. It checks for the presence and correctness of the Retry-After header, quota reset timestamps, current usage counters, and a human-readable explanation that helps the caller self-correct without reading external documentation. Run this prompt before a new API version goes live, when onboarding a new API product to a gateway, or when a customer reports confusion about rate limit errors. If the prompt flags missing elements, treat them as a pre-release checklist before the response reaches production traffic.

This prompt is designed to be pasted directly into your AI harness. It evaluates a single API error response against a structured rubric, checking for the presence and quality of critical headers, body fields, and human-readable explanations. The output is a scored report that can be used as a gate in a CI/CD pipeline or as part of a manual API design review.

textCopy
You are an API design reviewer specializing in developer experience for rate-limited endpoints. Your task is to evaluate the provided HTTP response for a 429 Too Many Requests error. You will produce a structured JSON report assessing its completeness, clarity, and adherence to common standards.

## INPUT
[HTTP_RESPONSE]
(Provide the full HTTP response, including status line, headers, and body.)

## EVALUATION CRITERIA
1. **Header Completeness:** Does the response include a `Retry-After` header (HTTP-date or delta-seconds)? Is there an `X-RateLimit-*` header set (e.g., `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`)?
2. **Body Clarity:** Does the JSON body contain a human-readable `message` field that explains the situation without exposing internal architecture? Does it include a machine-readable `error_code`?
3. **Actionability:** Does the response provide the client with enough information to understand *when* to retry and *how* to avoid the limit in the future? Does it state the current usage versus the limit?
4. **Standard Conformance:** Does the response body structure conform to a provided standard like RFC 7807 (Problem Details)?

## CONSTRAINTS
- Do not penalize the response for the specific rate limit window or quota value; only evaluate the *communication* of that information.
- If a header or field is missing, note it as a finding and deduct points from the relevant category.
- Be strict about the `Retry-After` header; its absence is a critical failure.

## OUTPUT_SCHEMA
Return a single valid JSON object matching this schema:
{
  "overall_score": number (0-100),
  "header_evaluation": {
    "score": number (0-40),
    "findings": [
      {
        "header_name": string,
        "status": "present" | "missing" | "malformed",
        "value": string,
        "comment": string
      }
    ]
  },
  "body_evaluation": {
    "score": number (0-40),
    "findings": [
      {
        "field_path": string,
        "status": "present" | "missing" | "unclear",
        "comment": string
      }
    ]
  },
  "actionability_score": number (0-20),
  "critical_failure": boolean,
  "developer_experience_summary": string
}

## RISK_LEVEL
Low. This is a design evaluation, not a runtime safety check.

To adapt this template, replace the [HTTP_RESPONSE] placeholder with the raw text of the error response you are testing. If your organization has a specific internal standard for error bodies, you can add it as a new section titled ## INTERNAL_STANDARD and reference it in the CONSTRAINTS block. The OUTPUT_SCHEMA is designed to be parsed by an automated script; ensure your AI harness validates the JSON before passing the score to a dashboard or CI system. For high-stakes API releases, always pair this automated evaluation with a human review of the developer_experience_summary to catch subtle tone or wording issues the rubric might miss.

This prompt is designed to operate as a design-time reviewer, not a runtime interceptor. The most effective harness places it inside a pull request checklist or an API design review gate. When an engineer proposes a new rate limit error response—or modifies an existing one—the prompt evaluates the response payload and headers against your organization's standards for developer experience, RFC compliance, and diagnostic completeness. The harness should capture the raw HTTP response (status line, headers, and body) and pass it as the [RATE_LIMIT_RESPONSE] input, along with any internal error response standards as [STANDARDS]. The model returns a structured evaluation that can be posted as a PR comment or stored in a design review system.

For CI integration, wrap the prompt in a script that extracts sample error responses from integration tests or contract tests. After your API test suite exercises the rate limit endpoint, capture the 429 response and pipe it to the model. Parse the JSON output and fail the build if the developer_experience_score falls below your threshold (we recommend 7/10 as a starting floor) or if any critical_findings array is non-empty. Log the full evaluation as a build artifact so engineers can see exactly which fields, headers, or explanations were missing. For teams using OpenAPI or gRPC schemas, include the relevant schema fragment as [API_SPEC] so the model can cross-check that the error response conforms to the documented contract—this catches the common failure mode where the spec says one thing and the implementation returns another.

Model choice matters here. This is a structured evaluation task with moderate reasoning depth. GPT-4o, Claude 3.5 Sonnet, or equivalent frontier models produce reliable structured output with consistent scoring. Smaller or older models tend to hallucinate header names, invent RFC references, or produce inconsistent scores across similar inputs. If you must use a smaller model, add a validator harness that checks the output JSON against a strict schema before accepting it: confirm retry_after_header_present is a boolean, current_usage_included is a boolean, developer_experience_score is an integer between 1 and 10, and critical_findings is an array of strings. On validation failure, retry once with the same input and a stronger constraint instruction. If the second attempt also fails, escalate to a human reviewer rather than silently accepting a malformed evaluation. For high-traffic API products where rate limit errors affect paying customers, add a periodic audit mode: sample 429 responses from production logs weekly, run them through this prompt, and trend the scores over time to catch regressions before customers complain.