chenhg5/cc-connect · error

qq: API %s failed (retcode=%d)

Error message

qq: API %s failed (retcode=%d)

What it means

Returned by callAPI when the OneBot server answered the request but with retcode != 0, meaning the action itself failed on the QQ/OneBot side. The message includes the action name and the numeric retcode so the caller can map it to a OneBot v11 failure code (e.g. 100 = missing params, 1200 = bad QQ level, async/failed codes).

Source

Thrown at platform/qq/qq.go:575

	p.mu.Lock()
	err = p.conn.WriteMessage(websocket.TextMessage, data)
	p.mu.Unlock()
	if err != nil {
		return nil, fmt.Errorf("qq: ws write: %w", err)
	}

	select {
	case raw := <-ch:
		var resp struct {
			Status  string          `json:"status"`
			RetCode int             `json:"retcode"`
			Data    json.RawMessage `json:"data"`
		}
		if json.Unmarshal(raw, &resp) != nil {
			return nil, fmt.Errorf("qq: invalid API response")
		}
		if resp.RetCode != 0 {
			return nil, fmt.Errorf("qq: API %s failed (retcode=%d)", action, resp.RetCode)
		}
		var result map[string]any
		_ = json.Unmarshal(resp.Data, &result)
		return result, nil

	case <-time.After(15 * time.Second):
		return nil, fmt.Errorf("qq: API %s timeout", action)
	}
}

// callHTTPAPI calls a OneBot v11 HTTP endpoint (e.g. /upload_group_file).
// Used for file operations — avoids WebSocket message size limits and
// file-path issues across Windows/WSL/Docker boundaries.
// Requires http_url to be configured.
func (p *Platform) callHTTPAPI(action string, params map[string]any) (map[string]any, error) {
	if p.httpURL == "" {
		return nil, fmt.Errorf("qq: http_url not configured")
	}

View on GitHub (pinned to 4000b2338a)

Solutions

  1. Look up the retcode in OneBot v11 docs: 100 invalid params, 102 access denied, 1200 account issue — fix the matching cause.
  2. Verify the target group_id/user_id exists and the bot is a member with send permission.
  3. Retest with a trivial message; if that fails too, the problem is the bot account or OneBot instance, not your payload.
  4. Check OneBot implementation logs for the underlying QQ-side failure (risk control events are often logged there).
  5. Update the OneBot implementation if the retcode corresponds to a known bug in your version.
Defensive patterns

Strategy: try-catch

Try / catch

_, err := p.callAPI("send_group_msg", params)
if err != nil {
    var retcode int
    if _, scan := fmt.Sscanf(err.Error(), "qq: API send_group_msg failed (retcode=%d)", &retcode); scan == nil {
        switch retcode {
        case 100:
            slog.Error("invalid params sent to onebot", "params", params)
        case 102:
            slog.Error("access denied: bot lacks permission in target")
        default:
            slog.Error("onebot action failed", "retcode", retcode, "err", err)
        }
    }
    return err
}

Prevention

When it happens

Trigger: Any callAPI action (send_group_msg, send_private_msg, get_group_info, etc.) where OneBot processes the request but rejects or fails it: invalid parameters, bot lacks permission, not in the group, message blocked by QQ risk control, or internal OneBot error.

Common situations: Bot removed from the group before sending; QQ risk-control blocking a message; wrong group_id/user_id in params; OneBot implementation bug or account restriction; retcode 1 (generic failed) from unsupported action.

Related errors

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