{"record":{"id":"8e09ac5eb8b6c9e1","repo":"chenhg5/cc-connect","slug":"qq-api-s-failed-retcode-d","errorCode":null,"errorMessage":"qq: API %s failed (retcode=%d)","messagePattern":"qq: API (.+?) failed \\(retcode=(.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"platform/qq/qq.go","lineNumber":575,"sourceCode":"\tp.mu.Lock()\n\terr = p.conn.WriteMessage(websocket.TextMessage, data)\n\tp.mu.Unlock()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"qq: ws write: %w\", err)\n\t}\n\n\tselect {\n\tcase raw := <-ch:\n\t\tvar resp struct {\n\t\t\tStatus  string          `json:\"status\"`\n\t\t\tRetCode int             `json:\"retcode\"`\n\t\t\tData    json.RawMessage `json:\"data\"`\n\t\t}\n\t\tif json.Unmarshal(raw, &resp) != nil {\n\t\t\treturn nil, fmt.Errorf(\"qq: invalid API response\")\n\t\t}\n\t\tif resp.RetCode != 0 {\n\t\t\treturn nil, fmt.Errorf(\"qq: API %s failed (retcode=%d)\", action, resp.RetCode)\n\t\t}\n\t\tvar result map[string]any\n\t\t_ = json.Unmarshal(resp.Data, &result)\n\t\treturn result, nil\n\n\tcase <-time.After(15 * time.Second):\n\t\treturn nil, fmt.Errorf(\"qq: API %s timeout\", action)\n\t}\n}\n\n// callHTTPAPI calls a OneBot v11 HTTP endpoint (e.g. /upload_group_file).\n// Used for file operations — avoids WebSocket message size limits and\n// file-path issues across Windows/WSL/Docker boundaries.\n// Requires http_url to be configured.\nfunc (p *Platform) callHTTPAPI(action string, params map[string]any) (map[string]any, error) {\n\tif p.httpURL == \"\" {\n\t\treturn nil, fmt.Errorf(\"qq: http_url not configured\")\n\t}","sourceCodeStart":557,"sourceCodeEnd":593,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/platform/qq/qq.go#L557-L593","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Look up the retcode in OneBot v11 docs: 100 invalid params, 102 access denied, 1200 account issue — fix the matching cause.","Verify the target group_id/user_id exists and the bot is a member with send permission.","Retest with a trivial message; if that fails too, the problem is the bot account or OneBot instance, not your payload.","Check OneBot implementation logs for the underlying QQ-side failure (risk control events are often logged there).","Update the OneBot implementation if the retcode corresponds to a known bug in your version."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"_, err := p.callAPI(\"send_group_msg\", params)\nif err != nil {\n    var retcode int\n    if _, scan := fmt.Sscanf(err.Error(), \"qq: API send_group_msg failed (retcode=%d)\", &retcode); scan == nil {\n        switch retcode {\n        case 100:\n            slog.Error(\"invalid params sent to onebot\", \"params\", params)\n        case 102:\n            slog.Error(\"access denied: bot lacks permission in target\")\n        default:\n            slog.Error(\"onebot action failed\", \"retcode\", retcode, \"err\", err)\n        }\n    }\n    return err\n}","preventionTips":["Map common OneBot retcodes to alerting in your integration","Validate group_id/user_id membership via get_group_info / get_stranger_info before sends","Watch for QQ risk-control by throttling message rates","Keep the OneBot implementation updated for fixed retcode bugs"],"tags":["onebot","api-error","retcode","qq"],"backgroundTag":"api-error-response","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}