chenhg5/cc-connect · error

qq: HTTP %s failed (retcode=%d, msg=%s)

Error message

qq: HTTP %s failed (retcode=%d, msg=%s)

What it means

callHTTPAPI returns this when the QQ OneBot HTTP API responded with valid JSON but a non-zero retcode, meaning the server itself rejected the action. retcode and the server's message are embedded so the specific API-level failure (bad parameter, auth failure, not found) is identifiable from the log.

Source

Thrown at platform/qq/qq.go:629

	}
	defer resp.Body.Close()

	raw, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, fmt.Errorf("qq: HTTP %s read body: %w", action, err)
	}

	var apiResp struct {
		Status  string          `json:"status"`
		RetCode int             `json:"retcode"`
		Data    json.RawMessage `json:"data"`
		Message string          `json:"message"`
	}
	if json.Unmarshal(raw, &apiResp) != nil {
		return nil, fmt.Errorf("qq: HTTP %s invalid response", action)
	}
	if apiResp.RetCode != 0 {
		return nil, fmt.Errorf("qq: HTTP %s failed (retcode=%d, msg=%s)", action, apiResp.RetCode, apiResp.Message)
	}
	var result map[string]any
	_ = json.Unmarshal(apiResp.Data, &result)
	return result, nil
}

// ── Helpers ─────────────────────────────────────────────────────

type replyContext struct {
	messageType string // "private" or "group"
	userID      int64
	groupID     int64
	messageID   int32
}

func (p *Platform) ReconstructReplyCtx(sessionKey string) (any, error) {
	// qq:{userID}, qq:{groupID}:{userID} or qq:g:{groupID}
	parts := strings.SplitN(sessionKey, ":", 3)

View on GitHub (pinned to 4000b2338a)

Solutions

1. Read retcode and msg from the error to identify the specific API failure (e.g. 4 = bot not in group).
2. If auth-related, verify the access_token in config matches the OneBot server's token.
3. Re-fetch group/friend lists or refresh the session if the target no longer exists.
4. Check the OneBot implementation's docs for the returned retcode's meaning.

// Go: verify bot membership before targeting a group
// call get_group_info / get_group_member_info first and bail out on retcode != 0

if err != nil {
    var apiErr *APIError // custom type holding RetCode/Msg parsed from the error string or wrapped value
    if errors.As(err, &apiErr) && apiErr.RetCode == 4 {
        // bot not in group: refresh group list or drop session
    }
    return err
}

When it happens

Trigger: apiResp.RetCode != 0 in callHTTPAPI: e.g. retcode=1 (invalid params to get_group_member_info/send_msg), retcode=3 (no support), retcode=4 (bot not in the target group), retcode failed auth (retcode=403/token mismatch in some implementations).

Common situations: Bot removed from a group but session still cached; wrong message_id after message recall; sending private messages to users who blocked the bot; access_token mismatch; OneBot implementation version differences in retcode semantics.

Related errors

• qq: API %s failed (retcode=%d)
• qq: send image: %w
• qq: API %s timeout
• qq: SendFile group: %w
• qq: SendFile private: %w

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/5ed9ea802cb64b68. Report an issue: GitHub.