What causes "Zhipu API returned status %d: %s" in Tencent/WeKnora?

Inspect the appended body detail to identify the actual blocker (HTML page = proxy/WAF, JSON = schema drift)

Zhipu API returned status %d: %s

Error message

Zhipu API returned status %d: %s

What it means

Fallback case of zhipuHTTPError: non-200 status, no parseable error object, but a non-empty body. The provider includes up to 4096 bytes of the trimmed raw body as detail so developers can see the actual failure payload.

Source

Thrown at internal/infrastructure/web_search/zhipu.go:240

	if len(body) > maxZhipuResponseBytes {
		return nil, fmt.Errorf("Zhipu response exceeds %d bytes", maxZhipuResponseBytes)
	}
	return body, nil
}

func zhipuHTTPError(statusCode int, body []byte) error {
	var response zhipuSearchResponse
	if err := json.Unmarshal(body, &response); err == nil && (response.Error.Code != "" || response.Error.Message != "") {
		return fmt.Errorf("Zhipu API returned status %d (%s): %s", statusCode, response.Error.Code, response.Error.Message)
	}
	detail := strings.TrimSpace(string(body))
	if len(detail) > 4096 {
		detail = detail[:4096]
	}
	if detail == "" {
		return fmt.Errorf("Zhipu API returned status %d", statusCode)
	}
	return fmt.Errorf("Zhipu API returned status %d: %s", statusCode, detail)
}

type zhipuSearchRequest struct {
	SearchQuery  string `json:"search_query"`
	SearchEngine string `json:"search_engine"`
	SearchIntent bool   `json:"search_intent"`
	Count        int    `json:"count"`
	ContentSize  string `json:"content_size"`
}

type zhipuSearchResponse struct {
	ID           string              `json:"id"`
	RequestID    string              `json:"request_id"`
	SearchResult []zhipuSearchResult `json:"search_result"`
	Error        zhipuError          `json:"error"`
}

type zhipuSearchResult struct {

View on GitHub (pinned to 988cbb0330)

Solutions

Inspect the appended body detail to identify the actual blocker (HTML page = proxy/WAF, JSON = schema drift)
Whitelist your egress IPs if a WAF block page appears
Update request/response handling to match the current Zhipu API error schema
Retry only if the detail indicates a transient 5xx condition

Example fix

// before
fmt.Println(err) // Zhipu API returned status 403: <html>blocked...</html>
// after
if strings.Contains(err.Error(), "<html") { log.Warn("proxy/WAF interference suspected") }

Defensive patterns

Strategy: try-catch

Validate before calling

if apiURL == "" || apiKey == "" { return errors.New("zhipu endpoint and key must be configured") }

Type guard

func hasBodyDetail(err error) (detail string, ok bool) {
    i := strings.Index(err.Error(), "): "); return "", i >= 0
}

Try / catch

results, err := provider.Search(ctx, q)
if err != nil {
    if strings.Contains(err.Error(), "<html") { log.Warn("WAF/proxy page detected in zhipu error body") }
    return err
}

Prevention

Read the appended body detail before deciding how to handle
Watch for HTML in error bodies — sign of WAF/CDN blocking
Whitelist egress IPs with the provider if blocks recur
Track API schema changes that move error fields

When it happens

Trigger: Calling Search() when Zhipu returns 4xx/5xx with an unstructured body (plain text, HTML error page, non-standard JSON shape).

Common situations: WAF/CDN blocking the client and returning an HTML block page; a gateway returning plain-text errors; API version change moving the error fields.

Related errors

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/c062ccb0f94229d4. Report an issue: GitHub.