What causes "Notion API error (%d): %s" in gastownhall/beads?

Read the raw body in the message to see who actually produced the error (Notion vs. a proxy).

Notion API error (%d): %s

Error message

Notion API error (%d): %s

What it means

Fallback error when Notion returns a non-2xx response whose body is NOT a parseable JSON error with a message (or json.Unmarshal fails). The raw (trimmed) body is included in the message. Indicates either an unexpected server-side response (HTML error page from a proxy, empty body) or a non-JSON gateway response.

Source

Thrown at internal/notion/client.go:301

	}
	defer func() { _ = resp.Body.Close() }()

	body, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseBytes))
	if err != nil {
		return nil, fmt.Errorf("read response: %w", err)
	}
	if resp.StatusCode >= 200 && resp.StatusCode < 300 {
		return body, nil
	}

	var apiErr struct {
		Code    string `json:"code"`
		Message string `json:"message"`
	}
	if err := json.Unmarshal(body, &apiErr); err == nil && apiErr.Message != "" {
		return nil, fmt.Errorf("Notion API error %s (%d): %s", apiErr.Code, resp.StatusCode, apiErr.Message)
	}
	return nil, fmt.Errorf("Notion API error (%d): %s", resp.StatusCode, strings.TrimSpace(string(body)))
}

View on GitHub (pinned to 71377f2769)

Solutions

Read the raw body in the message to see who actually produced the error (Notion vs. a proxy).
Check https://status.notion.so for an ongoing incident; retry with backoff if it's a 5xx.
Verify no proxy/WAF is intercepting api.notion.com (try from a different network or curl the endpoint).
If persistent and the body is an HTML block page, work with network admin to allow Notion API traffic.

Example fix

// before
if err != nil { return err } // Notion API error (502): <html>Bad Gateway</html>

// after
var apiErr *notion.APIError
if errors.As(err, &apiErr) && apiErr.StatusCode >= 500 {
    return retryWithBackoff(ctx, op) // transient upstream error
}
return err

Defensive patterns

Strategy: fallback

Try / catch

var apiErr *notion.APIError
if errors.As(err, &apiErr) && apiErr.StatusCode >= 500 {
    // transient/upstream: retry with backoff
} else if strings.Contains(err.Error(), "Notion API error (") {
    // non-JSON body: inspect raw message, likely proxy or outage
}

Prevention

Check status.notion.so during incidents; add retries for 5xx.
Ensure no WAF/proxy intercepts api.notion.com in your environment.
Log the full error message (it contains the raw body) for diagnosis.

When it happens

Trigger: Notion outage returning HTML/plain-text error pages via a load balancer; a corporate proxy intercepting and returning its own error page; 502/504 from an intermediary; empty response body with an error status; Notion changing its error payload shape.

Common situations: Company firewall blocking api.notion.com and returning an HTML block page; WAF rejecting the request; transient Notion incidents (status.notion.so) returning non-JSON 5xx responses.

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/dd9bd41902bb695d. Report an issue: GitHub.