Retry Guidance Prompt for Transient Errors

This prompt is designed for SDK engineers and platform teams who need to generate precise, actionable retry strategy documentation for every error code in an API surface. The output feeds directly into client library implementations, developer documentation, and operational runbooks. Use this prompt when you have a defined set of error codes and need to specify the backoff algorithm, maximum attempts, jitter parameters, and idempotency requirements for each one.

The prompt assumes you can provide the error code, the HTTP method, the endpoint category, and whether the operation is idempotent. It is most effective when your API has clear error semantics and you need to enforce consistent retry behavior across all client SDKs. The generated guidance should be treated as a draft that requires engineering review, particularly for non-idempotent operations where a blind retry could duplicate charges, create duplicate resources, or trigger unintended side effects.

Do not use this prompt for generating generic HTTP retry advice or for APIs where the error semantics are not yet defined. It is not a substitute for circuit breaker implementation, nor does it replace load-shedding decisions at the infrastructure layer. If your error codes lack clear idempotency guarantees or your API surface is still evolving, invest in defining those contracts first. For high-risk financial or healthcare operations, always route the generated retry guidance through a human approval step before it reaches production client code.

This prompt template generates a complete retry strategy document for a single error code. It is designed to be embedded in an SDK documentation pipeline or used by an API platform team to ensure every transient error has a consistent, machine-readable retry policy. The output includes the backoff algorithm, max attempts, jitter parameters, idempotency requirements, and circuit breaker integration points. Replace each square-bracket placeholder with the specific error code, method signature, and operational constraints before sending the prompt to the model.

textCopy
You are an expert SDK engineer documenting retry policies for a client library.

Generate a complete retry strategy document for the following transient error.

ERROR CODE: [ERROR_CODE]
HTTP STATUS: [HTTP_STATUS]
API METHOD: [HTTP_METHOD] [ENDPOINT_PATH]
OPERATION DESCRIPTION: [OPERATION_DESCRIPTION]
IDEMPOTENCY: [IDEMPOTENT_OR_NOT]
RETRYABLE EXCEPTION TYPES: [EXCEPTION_LIST]

OUTPUT SCHEMA:
{
  "error_code": "string",
  "retry_strategy": {
    "algorithm": "exponential_backoff | constant_delay | decorrelated_jitter",
    "initial_delay_ms": number,
    "max_delay_ms": number,
    "backoff_multiplier": number,
    "jitter": "full | equal | none",
    "max_attempts": number,
    "total_timeout_ms": number
  },
  "idempotency_requirements": {
    "is_idempotent": boolean,
    "idempotency_key_header": "string | null",
    "idempotency_key_source": "client_generated_uuid | request_body_hash | none",
    "retry_safety_note": "string"
  },
  "circuit_breaker": {
    "enabled": boolean,
    "failure_threshold": number,
    "recovery_timeout_ms": number,
    "half_open_max_requests": number
  },
  "retry_conditions": [
    {
      "condition": "string",
      "should_retry": boolean,
      "rationale": "string"
    }
  ],
  "code_example": {
    "language": "python | javascript | java | go",
    "snippet": "string"
  },
  "warnings": ["string"]
}

CONSTRAINTS:
- If the operation is non-idempotent, max_attempts must be 1 and the warnings field must explain the risk of double-processing.
- The code_example must demonstrate the full retry loop, including jitter, backoff, and circuit breaker integration.
- Every retry_condition must reference a specific HTTP status code, exception type, or error body pattern.
- Warnings must flag any scenario where a retry could cause data corruption, duplicate side effects, or cascading failures.
- The total_timeout_ms must be less than any upstream client timeout.

[EXAMPLES]

[TOOLS]

[RISK_LEVEL]

After copying this template, replace every placeholder with concrete values from your API specification. For non-idempotent operations like POST requests that create resources, set max_attempts to 1 and add a warning that the client must not retry without an idempotency key. For GET requests with 429 or 503 responses, use exponential backoff with full jitter and a circuit breaker that opens after 5 consecutive failures. The code example should be written in the primary language of your SDK. Before publishing, validate the output against your API's actual retry behavior by running the generated code snippet against a test endpoint that returns the target error code.

This prompt is designed to be called programmatically as part of an SDK documentation generation pipeline. The primary integration point is a script or CI job that iterates over a structured error code catalog (JSON or YAML), feeding each error code and its metadata into the prompt. The prompt expects [ERROR_CODE], [HTTP_STATUS], [ERROR_DESCRIPTION], [OPERATION_TYPE], and [IDEMPOTENCY_REQUIREMENT] as inputs. The output is a structured retry strategy block that can be directly embedded into SDK method documentation or a RetryPolicy configuration object. Do not use this prompt for non-transient errors (4xx client errors except 429) or for operations where the side effects are unknown—those require human-authored guidance.

The implementation harness should validate the model's output against a strict schema before accepting it. Define a JSON schema that requires: retryable (boolean), backoff_algorithm (enum: exponential, linear, decorrelated_jitter), base_delay_ms (integer), max_delay_ms (integer), max_attempts (integer), jitter (boolean), idempotency_required (boolean), and circuit_breaker_recommended (boolean). After the model responds, parse the output and validate it against this schema. If validation fails, retry the prompt once with the validation error appended to [CONSTRAINTS]. If it fails again, log the failure and route the error code to a human review queue. For high-risk operations where idempotency_required is true, always require human approval before publishing the retry guidance, regardless of schema validity. This prevents unsafe retry recommendations on non-idempotent writes like payment capture or resource deletion.

Model choice matters here. Use a model with strong JSON mode and instruction-following capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set temperature=0 to maximize determinism. For SDK generation at scale, batch error codes into groups of 10-20 per API call to reduce latency while staying under context limits. Implement a circuit breaker in the harness itself: if more than 10% of error codes in a batch fail validation after retries, halt the pipeline and alert the documentation team. Log every prompt invocation with the error code, model response, validation result, and reviewer decision. These logs become audit evidence for SDK release gates and help debug prompt drift over time. Avoid wiring this prompt directly into a customer-facing chatbot—retry guidance must be pre-computed, reviewed, and shipped as static documentation, not generated on the fly.