cc-api-proxy-safety

API Proxy Response Determination Security Specification

When implementing response determination in gateways, reverse proxies, WAFs, and CDN middleware, do not rely solely on body keywords to determine whether the upstream has failed. Keywords can serve as clues but cannot replace HTTP status, response headers, content type, and business response structure.

---

Core Principles

Determine the nature of the response according to the following priorities:

1. Transport layer and HTTP status: connection failures, timeouts, and non-2xx/3xx status codes take priority as error evidence.
2. Response headers and content type:Content-Type、Server、Via、CF-Ray, authentication/rate-limiting headers, etc. are more reliable than body keywords.
3. Business response structure: first parse contract fields such as the JSON envelope, error code, message, and data.
4. Body heuristics: only when determination cannot be made by structure should keywords or HTML fragments be used, with length and context limited.

Prohibited: performing pure strings.Contains(lowerBody, "cloudflare") / "bad gateway" / "error" misjudgment on the complete business body.

---

Splitting Strong and Weak Signals

Strong signals

Strong signals should also have clear context, for example:

• HTTP status is 502/503/504/429, and the body is an upstream error page or error envelope.
• Content-Type: text/html, the body contains an error page title, and the response headers or status also point to CDN/WAF/gateway.
• Structured JSON explicitly provides upstream error fields, for example {"error": {"type": "upstream_error"}}。

Do not treat a single short fragment directly as a strong signal.<html、cf-ray:、cloudflare、502 bad gateway may all appear in technical articles, log displays, or user input.

Weak signals

The following can only serve as weak evidence:

• CDN/gateway brand words:cloudflare、openresty、nginx
• Short error phrases:bad gateway、502 bad gateway、upstream error
• Generic error words:error、reconnecting、too many requests

Weak signals may participate in error determination only when the following conditions are met:

• The response body is very short, for example <= 512 bytes.
• The response structure is not a valid business payload.
• Or it appears simultaneously with an error HTTP status, error response headers, or an error content-type.

---

Determination Template

func isUpstreamFailure(resp *http.Response, body []byte) bool {
    if resp == nil {
        return true
    }

    status := resp.StatusCode
    contentType := strings.ToLower(resp.Header.Get("Content-Type"))

    if status >= 500 || status == http.StatusTooManyRequests {
        low := strings.ToLower(string(body))
        return looksLikeGatewayError(contentType, low, len(body))
    }

    if isValidBusinessPayload(contentType, body) {
        return false
    }

    if len(body) > 512 {
        return false
    }

    low := strings.ToLower(string(body))
    if len(body) <= 512 && containsWeakGatewayKeyword(low) {
        return true
    }

    return false
}

During implementation, test looksLikeGatewayError、isValidBusinessPayload、containsWeakGatewayKeyword separately; do not write all conditions into one large if。

---

Scenario Strategies

Scenario	Strategy
HTTP non-2xx/3xx	Prioritize error determination by status code and response headers; use the body to supplement classification
Business JSON response	Parse contract fields first; do not misjudge just because data or the body contains technical words
Long text/articles/model output	Error determination based only on weak keywords is not allowed
Short error messages	Weak keywords may be used, but should still be combined with the call context
Streaming responses	Wait for a complete event, complete JSON chunk, or explicit error event before determining

---

Regression Testing

At least cover:

• No misjudgment when a long body contains Cloudflare / 502 Bad Gateway / bad gateway technical terms.
• Determine as an error when the short response body contains only 502 Bad Gateway and has no business structure.
• status=200 and valid business JSON.
• status=502 and HTML error pages are judged as errors.
• When a streaming half chunk hits a keyword, do not immediately judge it as an error.

---

Boundaries with related skills

skill	Relationship
cc-external-system-debugging	Upstream methodology: when encountering CDN/WAF/proxy anomalies, first capture the real request/response
cc-api-design-safety	This skill focuses on proxy判定 logic and does not replace API envelope design specifications
cc-ops-safety	This skill does not handle operations approvals, dangerous commands, or production configuration changes

---

Rule provenance

> 📋 本回复遵循：`cc-api-proxy-safety` - [章节]