Tencent/WeKnora · error

Zhipu API returned status

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.

Solutions

1. Inspect the appended body detail to identify the actual blocker (HTML page = proxy/WAF, JSON = schema drift)
2. Whitelist your egress IPs if a WAF block page appears
3. Update request/response handling to match the current Zhipu API error schema
4. 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") }

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

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

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
}

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

• Zhipu API returned status
• failed to execute Zhipu request
• failed to marshal Zhipu request
• failed to read Zhipu response
• failed to unmarshal Zhipu response

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

Appendix: 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)