Tencent/WeKnora · error

Zhipu API returned status %d

Error message

Zhipu API returned status %d

What it means

Fallback case of zhipuHTTPError: the API returned a non-200 status, the body had no parseable error object, and the trimmed body is empty. The caller only learns the numeric status code with no detail.

Source

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

		return nil, fmt.Errorf("failed to read Zhipu response: %w", err)
	}
	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"`
}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Log/check the status code: retry 5xx with backoff, fix auth on 401/403
2. Check Zhipu service status or upstream LB health for 5xx
3. Add request ID/trace headers if available to correlate with server logs
4. Treat repeated 5xx as provider outage and fall back to another search provider

Example fix

// before
if err != nil { return err }
// after
if err != nil {
    if strings.Contains(err.Error(), "503") { return ErrProviderUnavailable } // enables fallback
    return err
}

if apiURL == "" { return errors.New("zhipu endpoint not configured") }

func isEmptyStatusError(err error) bool { re := regexp.MustCompile(`status \d+$`); return re.MatchString(err.Error()) }

results, err := provider.Search(ctx, q)
if err != nil {
    if isEmptyStatusError(err) { return fallbackProvider.Search(ctx, q) } // bare 5xx likely outage
    return err
}

When it happens

Trigger: Calling Search() when Zhipu returns 4xx/5xx with an empty body (e.g. 502/503 from a load balancer, 401 with no body).

Common situations: Upstream gateway returning bare 502/503/504 during outages; auth middleware rejecting with an empty body.

Related errors

• Zhipu API returned status %d: %s
• invalid Zhipu search engine: %s
• invalid Zhipu content size: %s
• query is empty
• failed to marshal Zhipu request: %w

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