Third-Party API Resilience Contract Prompt

This prompt is designed for integration engineers, SREs, and backend architects who are actively evaluating a third-party API for production use. The core job-to-be-done is to transform static vendor documentation, SLA pages, and error code references into a structured, actionable resilience contract review. The output is not a simple summary; it is a formal audit that identifies gaps between the vendor's promises and the operational requirements of a production system, covering SLA commitments, error response handling, rate limit compliance, timeout defaults, and the blast radius of a vendor outage.

To use this prompt effectively, you must provide the raw or copied text from the vendor's official API documentation, their Service Level Agreement (SLA) terms, and their error code reference. The prompt is engineered to cross-reference these three inputs. For example, it will check if a documented 99.9% uptime SLA is backed by a clear error budget and financial penalty, or if a 429 Too Many Requests error code is accompanied by a Retry-After header specification. Without these specific source materials, the prompt will produce a low-confidence, speculative analysis that is unsuitable for an architectural decision record.

Do not use this prompt for reviewing internal services, database resilience, or client-side patterns. An internal gRPC service is governed by your own SLOs and error budgets, not a vendor contract. Similarly, a mobile app's offline queue is a client-side resilience pattern that requires a different evaluation framework. Using this prompt for those scenarios will produce irrelevant checks, such as looking for financial penalties in an internal SLA, and will miss critical failure modes like connection pool exhaustion or stale data display. For those use cases, refer to the sibling playbooks on Circuit Breaker Design Review or Client-Side Resilience Pattern Audit. After completing this review, the logical next step is to feed the identified risks into a Failure Mode and Effects Analysis (FMEA) prompt to quantify their potential impact on your specific system.

This template forces the model to act as an integration engineer auditing a vendor API for resilience gaps. It requires you to supply the vendor's actual documentation—API reference pages, SLA terms, error code lists, and rate limit policies—as the [VENDOR_DOCS] input. The prompt is designed to produce a consistent, machine-readable JSON output that your application can parse, store, and compare across multiple vendor reviews. Do not use this prompt for internal service-to-service contracts where you control both sides; those require a different review frame focused on implementation correctness rather than external dependency risk.

textCopy
You are an integration reliability engineer reviewing a third-party API for production resilience risks.

## INPUT
[VENDOR_DOCS]

## SYSTEM CONTEXT
Our system calls this vendor API for: [INTEGRATION_PURPOSE]
Criticality level: [CRITICALITY_LEVEL]
Expected call volume: [CALL_VOLUME]
Acceptable latency ceiling: [LATENCY_CEILING_MS]ms

## OUTPUT_SCHEMA
Return valid JSON matching this structure exactly:
{
  "vendor_name": "string",
  "review_date": "YYYY-MM-DD",
  "sla_summary": {
    "uptime_commitment": "string or null",
    "latency_commitment": "string or null",
    "support_response_time": "string or null",
    "sla_credit_terms": "string or null",
    "gaps": ["string observations about missing or weak SLA terms"]
  },
  "error_handling": {
    "documented_error_codes": ["list of error codes found in docs"],
    "retryable_errors": ["subset that are safe to retry"],
    "missing_error_documentation": ["gaps identified"],
    "timeout_defaults": {
      "connect_timeout_documented": true or false,
      "read_timeout_documented": true or false,
      "recommended_timeout_ms": number or null
    }
  },
  "rate_limiting": {
    "limit_type": "string describing the limit model",
    "limit_value": "string or null",
    "window": "string or null",
    "rate_limit_headers_documented": true or false,
    "burst_allowance": "string or null",
    "compliance_risk": "low" | "medium" | "high"
  },
  "outage_impact": {
    "failure_scenarios": ["list of plausible outage modes"],
    "blast_radius": "string describing what breaks if this API is down",
    "graceful_degradation_options": ["fallback paths available"],
    "recommended_circuit_breaker_threshold": "string recommendation"
  },
  "overall_risk_rating": "low" | "medium" | "high" | "critical",
  "recommendations": ["prioritized list of actions before production use"],
  "undocumented_failure_modes": ["failure scenarios the docs do not address"],
  "confidence": "high" | "medium" | "low"
}

## CONSTRAINTS
- Only use information present in [VENDOR_DOCS]. Do not invent API behavior.
- If a field cannot be determined from the documentation, use null or an empty array.
- Mark confidence as "low" when documentation is sparse or ambiguous.
- Flag missing timeout defaults as a high-severity finding.
- For undocumented failure modes, reason from what the docs omit, not from general API experience.

## EVALUATION CRITERIA
A valid output must:
1. Contain all top-level keys in the schema.
2. Set confidence accurately based on documentation completeness.
3. Never hallucinate error codes or SLA terms not present in the input.
4. Identify at least one undocumented failure mode if the docs lack timeout or error information.

Adapt this template by adjusting the [INTEGRATION_PURPOSE], [CRITICALITY_LEVEL], [CALL_VOLUME], and [LATENCY_CEILING_MS] placeholders to match your actual dependency context. The criticality level should drive the risk rating: a payment-processing dependency with no documented retryable errors should surface as "critical," while a non-essential analytics endpoint might tolerate "medium" risk. If your organization has a standard resilience contract template, replace the OUTPUT_SCHEMA with your internal format—but preserve the requirement to flag missing timeout defaults and undocumented failure modes, as these are the most common production surprises.

Before wiring this into an automated pipeline, run it against a vendor whose documentation you know well and compare the output to your manual assessment. If the model invents SLA terms or error codes, add a stronger constraint in the prompt or switch to a model with lower hallucination rates for structured extraction tasks. For high-risk integrations, always route the output to a human reviewer before accepting the contract as complete. Store each review as a versioned artifact so you can detect when a vendor's documentation changes and re-trigger the audit.

This prompt is designed to be called programmatically as part of an integration review pipeline, not as a one-off chat interaction. The typical harness wraps the LLM call in a function that accepts a structured input object (vendor name, API documentation text, observed error logs, and SLA excerpts) and returns a typed resilience contract object. Because the output drives architectural decisions about timeout budgets, circuit breaker thresholds, and fallback strategies, the harness must enforce schema validation before the result is accepted into any design document or ADR.

Wire the prompt through a service function that constructs the full prompt by injecting the [VENDOR_NAME], [API_DOCUMENTATION], [OBSERVED_ERROR_LOG], and [SLA_EXCERPTS] placeholders. On the response path, apply a JSON schema validator that checks for required fields: sla_gaps, error_response_risks, rate_limit_exposure, outage_impact_assessment, and recommended_contract_clauses. If validation fails, retry once with the validation error message appended as a correction instruction. Log the raw prompt, the model response, the validation result, and the retry count to your observability platform. For high-risk integrations (payment processors, auth providers, health data APIs), route the validated output to a human review queue before it is committed to the architecture repository.

Model choice matters here. Use a model with strong structured output support and a context window large enough to hold the full API documentation plus the prompt instructions. If the documentation exceeds the context window, pre-process it with a chunking strategy that extracts endpoint definitions, error code tables, and SLA sections before passing them into the prompt. Do not truncate error code tables mid-row. The harness should also enforce a timeout on the LLM call itself—if the model takes longer than 30 seconds, fail the call and escalate rather than silently accepting a partial or hallucinated contract review.