chenhg5/cc-connect · error

HTTP %d: %s

Error message

HTTP %d: %s

What it means

subscribe performs the webhook subscription HTTP request and returns this error when the MAX API responds with status >= 300. The message embeds the status code and up to 1KB of the response body for diagnosis.

Source

Thrown at platform/max/max.go:355

	}
	body, err := json.Marshal(payload)
	if err != nil {
		return err
	}
	req, err := http.NewRequestWithContext(ctx, http.MethodPost, p.apiBase+"/subscriptions", bytes.NewReader(body))
	if err != nil {
		return err
	}
	p.setAuth(req)
	req.Header.Set("Content-Type", "application/json")
	resp, err := p.client.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	if resp.StatusCode >= 300 {
		respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
		return fmt.Errorf("HTTP %d: %s", resp.StatusCode, respBody)
	}
	return nil
}

// unsubscribe removes the webhook registration. Only used during Stop().
func (p *Platform) unsubscribe(ctx context.Context, url string) error {
	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, p.apiBase+"/subscriptions", nil)
	if err != nil {
		return err
	}
	p.setAuth(req)
	q := req.URL.Query()
	q.Set("url", url)
	req.URL.RawQuery = q.Encode()
	resp, err := p.client.Do(req)
	if err != nil {
		return err
	}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Read the embedded status code and body: 401/403 → fix the bot token and its scopes.
2. 400 → validate the webhook URL format and reachability requirements.
3. 429/5xx → back off and let the resubscribe loop retry; do not hammer the endpoint.
4. Log respBody in your monitoring to catch API-side changes.

if !strings.HasPrefix(webhookURL, "https://") { return errors.New("webhook URL must be https") }

if err := p.Start(handler); err != nil {
    var statusErr string
    if strings.Contains(err.Error(), "HTTP 401") || strings.Contains(err.Error(), "HTTP 403") {
        // do not retry: fix token first
    } else if strings.Contains(err.Error(), "HTTP 5") {
        // retry with exponential backoff
    }
    _ = statusErr
}

When it happens

Trigger: Any non-2xx response from the MAX subscribe endpoint: 400 for malformed URL, 401/403 for bad token or missing scopes, 5xx for server-side issues, hit during Start or the periodic resubscribeLoop.

Common situations: Expired bot token (401), webhook URL with disallowed scheme/host (400), MAX API outage (503), rate limiting (429) during aggressive resubscribes.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• subscribe: %w
• request usage endpoint: %w
• usage endpoint returned status %d: %s
• decode usage response: %w
• fetch presets: %w

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