Rate Limit Header Interpretation Prompt

This prompt is designed for API consumers—SDK engineers, integration developers, and backend service owners—who need to programmatically parse and interpret rate limit headers from HTTP responses. The core job-to-be-done is converting raw, often vendor-specific header strings into a structured, machine-readable object that can drive automated retry logic, backoff timers, and client-side throttling. The ideal user is implementing resilient API clients and needs a reliable, testable interpretation layer that handles the ambiguity of real-world headers before the retry policy consumes the data.

Use this prompt when you are building or maintaining client code that must respect server-imposed rate limits. It is appropriate when you have access to the raw response headers and need to extract the remaining quota, reset time, and a recommended Retry-After duration. The prompt is specifically designed to handle common header formats like X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, and RateLimit-* draft standards. It is not a replacement for a full HTTP client library, nor should it be used to make the actual retry decision; its output is a structured interpretation that your application code should validate and act upon. Do not use this prompt for server-side rate limit enforcement, capacity planning, or generating human-readable dashboards without further processing.

Before using this prompt, ensure you have captured the full set of rate-limit-related headers from the HTTP response. The prompt requires a raw header string or a structured list of key-value pairs as input. It is critical to understand that the prompt's interpretation is a best-effort synthesis; conflicting or missing headers will be flagged in the output, and your application must decide how to resolve them. The next step after generating the interpretation is to feed the structured output into your retry and backoff logic, applying your own safety bounds (e.g., a maximum backoff ceiling) regardless of the prompt's recommendation.

This prompt template is designed to parse raw HTTP rate limit headers and produce a structured, actionable interpretation. It handles common header formats like X-RateLimit-*, RateLimit-*, Retry-After, and X-RateLimit-Reset, and it is built to be wired directly into an API client's retry handler or a monitoring dashboard. The template uses square-bracket placeholders so you can inject the raw headers, your application's specific constraints, and the desired output schema at runtime.

textCopy
You are an API infrastructure assistant. Your task is to parse a set of HTTP rate limit headers and produce a structured JSON interpretation.

## INPUT
Raw HTTP response headers:
[RAW_HEADERS]

## CONSTRAINTS
- Default to UTC for all timestamps.
- If multiple rate limit windows are present (e.g., per-second and per-minute), report each separately.
- If a header is missing or malformed, note it in the `warnings` array and do not fabricate values.
- For the `reset_in_seconds` field, calculate the delta from the current time provided.
- [ADDITIONAL_CONSTRAINTS]

## OUTPUT SCHEMA
Return a single JSON object matching this structure:
{
  "limits": [
    {
      "window": "second|minute|hour|day|unknown",
      "remaining": <integer or null>,
      "limit": <integer or null>,
      "reset_utc": "<ISO 8601 datetime or null>",
      "reset_in_seconds": <integer or null>,
      "retry_after_seconds": <integer or null>,
      "source_header": "<the raw header name used>"
    }
  ],
  "recommended_action": "retry|wait|stop|proceed",
  "backoff_strategy": "<exponential|linear|none>",
  "warnings": ["<description of any missing, conflicting, or unparseable headers>"]
}

## INSTRUCTIONS
1. Parse all standard rate limit headers (X-RateLimit-*, RateLimit-*, Retry-After, X-RateLimit-Reset).
2. Normalize the reset time to UTC ISO 8601. If a Unix timestamp is provided, convert it.
3. If `Retry-After` is present, it takes precedence for the `retry_after_seconds` value.
4. If `remaining` is 0, set `recommended_action` to "wait" and calculate `retry_after_seconds` from the reset time.
5. If no rate limit headers are present, set `recommended_action` to "proceed" and add a warning.
6. If headers conflict (e.g., two different reset times for the same window), include both limits and add a warning.
7. Output only the JSON object. No markdown, no explanation.

Current UTC time: [CURRENT_UTC_TIME]

To adapt this template, replace the square-bracket placeholders with your runtime data. [RAW_HEADERS] should be a stringified map of header names to values, such as X-RateLimit-Remaining: 0, Retry-After: 120. [ADDITIONAL_CONSTRAINTS] can inject domain-specific rules, like 'never retry on 5xx errors without human review' or 'cap max backoff at 300 seconds'. [CURRENT_UTC_TIME] must be the actual time the response was received, which is critical for calculating accurate reset_in_seconds values. Before deploying, validate the output against your schema in a test harness and add a retry layer that reads the recommended_action and backoff_strategy fields to control client behavior.

This prompt is designed to sit inside an API client's retry middleware, not as a standalone chatbot. The typical integration point is immediately after receiving a 429 Too Many Requests or any response containing rate limit headers. The application should extract the raw header values from the HTTP response object and pass them into the prompt as structured input. The model's structured output then feeds directly into the client's backoff controller, determining the next retry delay and whether to pause all outbound requests to that endpoint.

The implementation should follow a strict validate-then-act pattern. Before using the model's output to schedule a retry, validate the parsed fields: retry_after_seconds must be a positive integer or float, remaining_quota must be an integer (or null with a logged warning), and reset_timestamp_utc must parse as a valid ISO-8601 datetime in the future. If validation fails, fall back to a configurable default exponential backoff with jitter. Log every validation failure alongside the raw headers and the model's raw output so you can tune the prompt or add header-format normalization later. For high-throughput clients, consider caching the interpretation for the reset_timestamp_utc window to avoid calling the model on every 429 response from the same endpoint.

Model choice matters here. This is a structured extraction task with low ambiguity, so a fast, cheaper model (e.g., GPT-4o-mini, Claude Haiku) is usually sufficient. Set temperature=0 and enforce the JSON output schema through the model's native structured output feature or function-calling API. Do not rely on parsing free-text responses. Wire the prompt into a retry budget: if the model fails to produce valid JSON three times in a row, or if the total interpretation latency exceeds your retry window, fall back to the default backoff strategy and increment a prompt_failure counter on your observability dashboard. This prompt should never become a new single point of failure in your retry logic.