chenhg5/cc-connect · error

gateway request failed: %w

Error message

gateway request failed: %w

What it means

Returned by the gateway URL fetch when the HTTP request to the QQ gateway endpoint (Authorization: QQBot <token>) fails at the transport level — connection error, timeout, or request construction failure. No gateway URL can be obtained, so the WS connection cannot proceed.

Source

Thrown at platform/qqbot/qqbot.go:694

	// so we can cancel them cleanly on reconnect.
	connCtx, connCancel := context.WithCancel(ctx)
	p.connCancel = connCancel
	go p.heartbeatLoop(connCtx)
	go p.readLoop(connCtx)

	return nil
}

func (p *Platform) getGatewayURL(token string) (string, error) {
	req, err := http.NewRequest("GET", p.apiBase()+"/gateway/bot", nil)
	if err != nil {
		return "", err
	}
	req.Header.Set("Authorization", "QQBot "+token)

	resp, err := core.HTTPClient.Do(req)
	if err != nil {
		return "", fmt.Errorf("gateway request failed: %w", err)
	}
	defer resp.Body.Close()

	var result struct {
		URL string `json:"url"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return "", fmt.Errorf("gateway response decode: %w", err)
	}
	if result.URL == "" {
		return "", fmt.Errorf("empty gateway URL in response")
	}
	return result.URL, nil
}

type wsPayload struct {
	Op int             `json:"op"`
	D  json.RawMessage `json:"d,omitempty"`

View on GitHub (pinned to 4000b2338a)

Solutions

1. Check network connectivity to the QQ open-platform API host from the host machine
2. Verify the configured apiBase is the correct QQ API base URL
3. Increase the HTTP client timeout if it is too tight
4. Retry with exponential backoff; wrap so the app can reconnect later

if core.HTTPClient == nil || core.HTTPClient.Timeout == 0 {
    core.HTTPClient = &http.Client{Timeout: 15 * time.Second}
}

resp, err := core.HTTPClient.Do(req)
if err != nil {
    slog.Warn("gateway fetch failed, will retry", "err", err)
    time.Sleep(2 * time.Second)
    return getGatewayURL() // bounded retries
}

When it happens

Trigger: core.HTTPClient.Do(req) returns an error when fetching the gateway URL: DNS failure, refused connection, TLS error, or client timeout.

Common situations: Machine without internet access; QQ API endpoint temporarily down; an aggressive timeout in core.HTTPClient; wrong apiBase pointing to a nonexistent host in a test environment.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• qqbot: api request failed: %w
• qqbot: api retry failed: %w
• gateway response decode: %w
• range chunk retries exhausted
• request usage endpoint: %w

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