{"record":{"id":"35f34bb305f4c61f","repo":"larksuite/cli","slug":"connection-check-api-error-code-d-msg-q","errorCode":null,"errorMessage":"connection check: api error code=%d msg=%q","messagePattern":"connection check: api error code=(.+?) msg=%q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/event/consume/remote_preflight.go","lineNumber":34,"sourceCode":"// CheckRemoteConnections returns the count of active WebSocket connections for this app.\nfunc CheckRemoteConnections(ctx context.Context, client APIClient) (int, error) {\n\traw, err := client.CallAPI(ctx, \"GET\", \"/open-apis/event/v1/connection\", nil)\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"connection check: %w\", err)\n\t}\n\tvar result struct {\n\t\tCode int    `json:\"code\"`\n\t\tMsg  string `json:\"msg\"`\n\t\tData struct {\n\t\t\tOnlineInstanceCnt int `json:\"online_instance_cnt\"`\n\t\t} `json:\"data\"`\n\t}\n\tif err := json.Unmarshal(raw, &result); err != nil {\n\t\treturn 0, fmt.Errorf(\"connection check: decode: %w (body=%s)\", err, truncateForError(raw))\n\t}\n\t// Distinguish \"verified zero\" from \"check failed\" — non-zero code decodes Cnt=0.\n\tif result.Code != 0 {\n\t\treturn 0, fmt.Errorf(\"connection check: api error code=%d msg=%q\", result.Code, result.Msg)\n\t}\n\treturn result.Data.OnlineInstanceCnt, nil\n}\n\n// truncateForError bounds length and collapses control chars to defang log injection.\nfunc truncateForError(b []byte) string {\n\tconst max = 256\n\ts := event.TruncateDiagnostic(string(b), max, \"…(truncated)\")\n\tout := make([]byte, 0, len(s))\n\tfor _, r := range s {\n\t\tif r == '\\n' || r == '\\r' || r == '\\t' {\n\t\t\tout = append(out, ' ')\n\t\t\tcontinue\n\t\t}\n\t\tout = append(out, string(r)...)\n\t}\n\treturn string(out)\n}","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/internal/event/consume/remote_preflight.go#L16-L52","documentation":"The connection-check endpoint can return HTTP 200 with an application-level error inside the JSON envelope (code != 0); Go's json.Unmarshal succeeds but online_instance_cnt would misleadingly decode as 0. To distinguish a verified zero connections from a failed check, this error is raised with the API's code and msg verbatim. It represents a server-side rejection of the request, not a transport or parsing problem.","triggerScenarios":"CallAPI succeeded and JSON decoded, but result.Code is non-zero on GET /open-apis/event/v1/connection — e.g. invalid app credentials, app not enabled for long connections, or service-side rejection codes.","commonSituations":"Wrong app_id/secret configured for the consumer, app lacking the event/long-connection entitlement, tenant-side rate limiting or permission errors returned as app-level codes.","solutions":["Read code= and msg= from the error and look up that code in the Lark/Feishu API error code docs for the exact cause.","Verify the app credentials and that the app has long-connection/event subscription enabled.","Check scopes/permissions granted to the app for event connections.","Retry with backoff if the code indicates throttling; fix configuration if it indicates auth/permission."],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":"// After decoding, check the envelope code before trusting online_instance_cnt\nvar result struct {\n\tCode int `json:\"code\"`\n\tMsg  string `json:\"msg\"`\n\tData struct{ OnlineInstanceCnt int `json:\"online_instance_cnt\"` } `json:\"data\"`\n}\nif result.Code != 0 {\n\t// treat as API-level failure, not a zero-connection reading\n}","typeGuard":"func isAPISuccess(err error) bool {\n\treturn err == nil || !strings.Contains(err.Error(), \"api error code=\")\n}","tryCatchPattern":"cnt, err := consume.CheckRemoteConnections(ctx, client)\nif err != nil {\n\tvar code, msg int\n\tif _, scan := fmt.Sscanf(err.Error(), \"connection check: api error code=%d\", &code); scan == nil {\n\t\tswitch code {\n\t\tcase 99991663, 99991661: // token invalid/expired (example codes)\n\t\t\trefreshTokenAndRetry()\n\t\tdefault:\n\t\t\tlog.Fatalf(\"connection check rejected: code=%d\", code)\n\t\t}\n\t}\n}","preventionTips":["Verify app_id/app_secret and token rotation before startup preflight.","Ensure the app is entitled to long-connection/event subscription in the developer console.","Map known API codes to concrete remediations instead of generic failure handling.","Distinguish 'verified zero' from failure: never treat err != nil with cnt==0 as a healthy state."],"tags":["api-error","preflight","websocket","lark"],"backgroundTag":"api-error-code","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}