API Gateway Route Conflict Resolution Prompt

API platform engineers use this prompt when an API gateway returns 4xx or 5xx errors caused by route conflicts, overlapping path definitions, method mismatches, or broken backend integrations. The prompt reads the current gateway configuration and the specific error response to propose a corrected route definition or backend setting. This is a recovery prompt, not a design prompt. It assumes a working configuration exists and a specific failure has been identified. Use it inside an automated retry loop or as part of an on-call runbook where the operator pastes the error and config into a triage tool.

The prompt requires two concrete inputs: the gateway's current route configuration (in its native format—Kong declarative config, APISIX routes, AWS API Gateway OpenAPI spec, or similar) and the exact error response returned by the gateway (status code, body, and any X- headers). Without both, the model cannot isolate the conflicting route or misconfiguration. The output should be a corrected route definition or backend setting, accompanied by a one-line explanation of what changed and why. The harness should validate that the proposed config is syntactically valid for the target gateway before applying it.

Do not use this prompt for greenfield API design, for gateways where the configuration source of truth is unknown, or when the error is a transient network failure rather than a configuration conflict. If the error is a 502 or 504 with no route-level detail, the problem is likely downstream and this prompt will hallucinate a fix. Escalate to backend health checks instead. For high-traffic production gateways, always stage the proposed change in a canary or shadow deployment and run the gateway's own config validation (kong check, apisix validate, or equivalent) before promotion.

This prompt template is designed for API platform engineers who need to resolve routing conflicts or backend integration failures in an API gateway. It takes the current gateway configuration and the specific 4xx/5xx error as input, then proposes corrected route definitions or backend integration settings. The template uses square-bracket placeholders that you must replace with real values before sending it to the model.

textCopy
You are an expert API gateway engineer diagnosing and resolving route conflicts and integration failures.

## INPUT
- Gateway Configuration (JSON/YAML):
[GATEWAY_CONFIG]

- Error Context (status code, response body, logs):
[ERROR_CONTEXT]

## TASK
Analyze the provided gateway configuration and error context to identify the root cause of the routing conflict or integration failure. Propose a corrected configuration that resolves the issue.

## OUTPUT_SCHEMA
Return a valid JSON object with the following structure:
{
  "diagnosis": {
    "root_cause": "string describing the specific misconfiguration",
    "affected_route_or_integration": "string identifier",
    "error_type": "path_overlap | method_conflict | timeout | backend_unreachable | auth_failure | other"
  },
  "corrected_config": {
    "type": "route | integration | both",
    "patch": "the minimal corrected configuration snippet in the original format",
    "explanation": "string explaining what was changed and why"
  },
  "validation_checks": [
    "list of specific checks to run after applying the fix, e.g., 'Verify no path overlap with /users/{id}'",
    "e.g., 'Confirm timeout value exceeds backend p99 latency'"
  ]
}

## CONSTRAINTS
- Preserve all existing routes and integrations not directly involved in the conflict.
- Prefer minimal changes over complete rewrites.
- If the error is a timeout, do not simply increase the timeout without checking backend health.
- If the error is a path overlap, ensure the corrected paths are unambiguous and ordered correctly.
- Flag any proposed change that might break other routes.

## EXAMPLES
[OPTIONAL_EXAMPLES]

## RISK_LEVEL
[RISK_LEVEL: low | medium | high]

To adapt this template, replace each placeholder with real data. [GATEWAY_CONFIG] should contain the full or relevant subset of your gateway's route and integration definitions. [ERROR_CONTEXT] should include the HTTP status code, response body, and any relevant gateway logs. Use [OPTIONAL_EXAMPLES] to provide few-shot examples of correct diagnoses and patches for your specific gateway technology (e.g., AWS API Gateway, Kong, Apigee). Set [RISK_LEVEL] to guide the model's caution; for production gateways, use 'high' to enforce stricter validation checks. After receiving the output, always run the suggested validation_checks before applying the patch to a live environment.

This prompt is designed to be called after an API gateway (such as AWS API Gateway, Kong, or Apigee) returns a 4xx or 5xx error that indicates a routing or integration misconfiguration. The harness should capture the failing route definition, the exact error code and message, and any relevant gateway configuration context before invoking the model. Do not send raw access keys, secrets, or full request payloads to the model; redact sensitive fields and replace them with placeholder tokens in the [GATEWAY_CONFIG] and [ERROR_CONTEXT] inputs.

The implementation loop follows a strict validate-before-apply pattern. After the model returns a corrected route definition, the harness must parse the output and run a series of pre-apply checks: (1) verify the JSON or YAML structure matches the gateway's expected schema, (2) confirm that no path overlaps with existing routes unless intentional, (3) validate that HTTP methods are explicitly listed and do not conflict with sibling routes, and (4) check that timeout and retry settings fall within the gateway's allowed ranges. If any check fails, the harness should re-invoke the prompt with the specific validation error appended to [ERROR_CONTEXT] and increment a retry counter. Cap retries at three attempts before escalating to a human operator via the team's incident channel.

For logging and observability, record the original error, the model's proposed correction, the validation results, and the final applied configuration in a structured audit log. This trace is critical for post-incident review and for detecting patterns that may indicate a need to update the prompt's few-shot examples or constraints. When deploying to production, prefer a model with strong JSON mode and instruction-following capabilities (such as Claude 3.5 Sonnet or GPT-4o) and set temperature to 0 to maximize deterministic, repeatable corrections. Never auto-apply the model's output to a production gateway without the validation harness and, for high-traffic or revenue-critical routes, require a human approval step before the final PUT or PATCH call.