Webhook Rate Limiting Documentation Prompt

Use this prompt when you need to translate a defined rate limit policy—typically existing in code, configuration files, or an internal spec—into unambiguous, developer-facing documentation. The ideal user is a platform or infrastructure engineer who understands the system's throttling behavior but needs to produce clear, actionable guidance for external consumers. The prompt is designed to accept raw policy parameters (such as requests-per-second, burst multipliers, and window sizes) and generate a complete documentation section that covers per-consumer limits, burst allowances, the exact HTTP headers returned on every response, and the required consumer behavior upon receiving a 429 Too Many Requests status.

This prompt is not a policy design tool. Do not use it if your rate limits are undefined, still under debate, or vary per customer in ways that cannot be expressed as a single rule set. It is also not a substitute for load-testing your limits or verifying that your gateway enforces what you document. The prompt assumes you have already made the engineering decisions and need to communicate them. A critical feature of this playbook is its built-in validation step: the prompt is instructed to check the generated rate limit documentation for internal consistency with your existing retry policy and timeout documentation. This prevents the common failure mode where rate limit guidance tells consumers to retry immediately while the retry policy mandates exponential backoff, creating a conflicting and unusable integration experience.

Before using this prompt, gather your rate limit parameters, your current retry policy documentation, and your webhook timeout specifications. The prompt will require these as explicit inputs. After generation, you should still review the output for policy accuracy, but the consistency checks will catch the most dangerous class of errors—contradictory instructions. If your documentation set is large, consider running this prompt once per consumer tier or per endpoint group to keep the generated sections scoped and testable.

This prompt template produces structured documentation for webhook delivery rate limits. It covers per-consumer limits, burst allowances, rate limit headers, 429 response handling, and consistency checks against your existing retry policy and timeout documentation. Replace the square-bracket placeholders with your platform's specific configuration before running the prompt.

textCopy
You are a technical documentation engineer for a platform that delivers webhooks to consumer endpoints. Your task is to produce clear, accurate documentation of webhook rate limiting behavior.

## INPUTS
- Rate limit configuration: [RATE_LIMIT_CONFIG]
- Burst allowance policy: [BURST_ALLOWANCE_POLICY]
- Rate limit header specifications: [RATE_LIMIT_HEADERS]
- 429 response body schema: [429_RESPONSE_SCHEMA]
- Existing retry policy documentation: [RETRY_POLICY_DOCS]
- Existing timeout documentation: [TIMEOUT_DOCS]
- Consumer-facing documentation style guide: [STYLE_GUIDE]

## OUTPUT REQUIREMENTS
Generate documentation with these sections:
1. **Rate Limit Overview**: Explain the rate limiting model (e.g., sliding window, token bucket), the limit value, and the scope (per-endpoint, per-consumer, per-event-type).
2. **Burst Allowance**: Document any short-term burst capacity above the steady-state limit, including burst window duration and replenishment behavior.
3. **Rate Limit Headers**: Specify every response header the consumer should inspect, including header names, value formats, and interpretation guidance.
4. **429 Response Handling**: Document the exact HTTP 429 response body schema, including error codes, messages, and any `Retry-After` header behavior.
5. **Consumer Responsibilities**: Explain what the consumer must do when rate-limited, including backoff strategy, retry timing, and how to avoid cascading failures.
6. **Consistency Checks**: Explicitly note how the rate limit policy interacts with the retry policy and timeout configuration. Flag any edge cases where rate limiting could cause retry amplification or timeout mismatches.

## CONSTRAINTS
- Use exact values from [RATE_LIMIT_CONFIG]. Do not invent or approximate limits.
- If [BURST_ALLOWANCE_POLICY] is empty or "none", explicitly state that no burst is allowed.
- Every header in [RATE_LIMIT_HEADERS] must appear in the documentation with a usage example.
- The 429 response body must match [429_RESPONSE_SCHEMA] exactly, including field names and types.
- Cross-reference [RETRY_POLICY_DOCS] and [TIMEOUT_DOCS] by section name or anchor where conflicts could arise.
- Flag any inconsistency between rate limit windows and retry intervals as a **documentation gap** that requires human review.
- Write in the tone and format specified by [STYLE_GUIDE].

## OUTPUT FORMAT
Return the documentation as clean Markdown. Use tables for header specifications and response fields. Use callouts (blockquotes) for warnings and consistency notes.

## VALIDATION INSTRUCTIONS
After generating the documentation, append a **Validation Report** section that:
- Confirms every header from [RATE_LIMIT_HEADERS] is documented.
- Confirms the 429 schema matches [429_RESPONSE_SCHEMA].
- Lists any detected inconsistencies with retry policy or timeout docs.
- Marks each inconsistency as `WARNING` (minor) or `BLOCKER` (must fix before publication).

Adaptation guidance: Replace each square-bracket placeholder with your actual configuration values. The [RATE_LIMIT_CONFIG] should include the limit value, window type, and scope. The [STYLE_GUIDE] can be a short description of your documentation tone or a link to your style guide. If you don't have a burst policy, set [BURST_ALLOWANCE_POLICY] to "none" and the prompt will handle it explicitly. The validation report at the end acts as a built-in QA step before you publish the output.

What to do next: After running this prompt, review the Validation Report section for any BLOCKER inconsistencies. Resolve those with your platform team before publishing. If the prompt flags a documentation gap between your rate limit window and retry intervals, escalate that to the team that owns retry configuration. For high-risk platforms where rate limiting errors could cause data loss, always have a human review the final documentation before it reaches consumers.

This prompt is designed to be integrated into a documentation generation pipeline, not used as a one-off chat interaction. The primary integration point is after your platform team has defined rate limiting parameters in a structured configuration file or API specification. The prompt consumes those parameters as structured input and produces documentation sections that must be validated before publication. The harness should treat this prompt as a transformation step—structured config in, validated markdown out—with clear contracts on both sides.

Input contract: Before calling the model, assemble the [RATE_LIMIT_CONFIG] placeholder from your source of truth. This should be a JSON object containing: window_size (e.g., "60s"), max_requests (integer), burst_multiplier (float), rate_limit_header_names (array of strings like ["X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset"]), retry_after_header (boolean), scope ("per-consumer" or "per-endpoint"), and 429_response_body_schema (JSON Schema object). If your system has tiered limits, include a tiers array with name, max_requests, and burst_multiplier per tier. Output contract: The model should return a JSON object with keys rate_limit_overview (markdown string), headers_table (markdown table string), 429_response_documentation (markdown string), and retry_guidance (markdown string). Parse this JSON in your application layer before rendering. If the model returns malformed JSON, use a retry with repair prompt that includes the parse error and asks for corrected JSON. After three failed retries, escalate to a human reviewer with the raw output attached.

Validation and consistency checks: After successful JSON parsing, run automated validators before the documentation reaches a human reviewer. Check that every rate limit header mentioned in headers_table appears in the original [RATE_LIMIT_CONFIG] input—hallucinated headers are a common failure mode. Verify that the 429_response_body_schema in the output matches the input schema structurally (same required fields, same types). Cross-reference the retry guidance against your existing retry policy documentation: if the prompt recommends a Retry-After delay that contradicts your configured retry schedule, flag it. Human review gate: For any documentation that will be published to external consumers, require a human reviewer to approve the output. The reviewer should verify that burst allowance descriptions match actual gateway behavior and that example 429 responses are accurate. Log the input config, model output, validation results, and reviewer decision for audit trails. Model choice: Use a model with strong JSON mode support and low hallucination rates for structured generation tasks. This prompt benefits from models that can reason about consistency between rate limit parameters and their documentation implications. Avoid models that tend to add unsolicited "best practices" commentary not grounded in the input config.