{"record":{"id":"71e5c6af5bc7fb67","repo":"Tencent/WeKnora","slug":"server-error-d-s","errorCode":null,"errorMessage":"server error %d: %s","messagePattern":"server error (.+?): (.+?)","errorType":"http","errorClass":null,"httpStatus":500,"severity":"error","filePath":"internal/datasource/connector/notion/client.go","lineNumber":135,"sourceCode":"\t\t\treturn nil, fmt.Errorf(\"%w: %s\", datasource.ErrResourceNotFound, path)\n\n\t\tcase resp.StatusCode == 429:\n\t\t\tretryAfter := resp.Header.Get(\"Retry-After\")\n\t\t\twait := 1 * time.Second\n\t\t\tif secs, err := strconv.ParseFloat(retryAfter, 64); err == nil && secs > 0 {\n\t\t\t\twait = time.Duration(secs * float64(time.Second))\n\t\t\t}\n\t\t\tlogger.Warnf(ctx, \"[Notion] rate limited, retry after %v (attempt %d/%d)\", wait, attempt+1, maxRetries)\n\t\t\tlastErr = fmt.Errorf(\"rate limited: %s\", string(respBody))\n\t\t\tif attempt < maxRetries {\n\t\t\t\tif sErr := sleepWithContext(ctx, wait); sErr != nil {\n\t\t\t\t\treturn nil, sErr\n\t\t\t\t}\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\tcase resp.StatusCode >= 500:\n\t\t\tlastErr = fmt.Errorf(\"server error %d: %s\", resp.StatusCode, string(respBody))\n\t\t\tif attempt < maxRetries {\n\t\t\t\tif sErr := sleepWithContext(ctx, time.Duration(1<<attempt)*time.Second); sErr != nil {\n\t\t\t\t\treturn nil, sErr\n\t\t\t\t}\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\tdefault:\n\t\t\treturn nil, fmt.Errorf(\"unexpected status %d: %s\", resp.StatusCode, string(respBody))\n\t\t}\n\t}\n\n\tif lastErr != nil {\n\t\treturn nil, fmt.Errorf(\"%w: %v\", datasource.ErrFetchFailed, lastErr)\n\t}\n\treturn nil, datasource.ErrFetchFailed\n}\n","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/datasource/connector/notion/client.go#L117-L153","documentation":"The Notion API returned an HTTP 5xx server error. The client retries with exponential backoff (1s, 2s, 4s) up to maxRetries=3; this error escapes only when the server keeps failing across all attempts. It is then wrapped with datasource.ErrFetchFailed at client.go:149, so the surfaced error reads like `fetch failed: server error 502: ...` with the response body appended.","triggerScenarios":"Any doRequest call (Ping, GetPage, GetDatabaseInfo, GetDataSourceInfo, GetBlockChildrenFlat, getBlockChildrenRecursive) where the response status is >= 500 on every attempt (0 through 3). Typical statuses: 500, 502, 503 from Notion or an intermediate proxy/gateway.","commonSituations":"Notion platform incidents or degraded service (check status.notion.so); corporate proxies / API gateways returning 502/504; custom baseURL pointing at a misbehaving mirror or self-hosted proxy; transient Notion overload during heavy load.","solutions":["Retry the operation after a short delay — 5xx is usually transient on Notion's side.","Check Notion's status page (status.notion.so) for an ongoing incident.","Inspect the response body in the error message — a 502 HTML page indicates a proxy, not Notion itself.","If a proxy is in the path, verify proxy health / timeouts and that baseURL is correct (ValidateConnectorBaseURL passed, but the upstream may be wrong).","Increase maxRetries or backoff base in doRequest if your workload tolerates longer waits."],"exampleFix":"// before\ncase resp.StatusCode >= 500:\n    lastErr = fmt.Errorf(\"server error %d: %s\", resp.StatusCode, string(respBody))\n// after (optional): treat 503 specially with a floor backoff\nwait := time.Duration(1<<attempt) * time.Second\nif resp.StatusCode == http.StatusServiceUnavailable { wait = 5 * time.Second }","handlingStrategy":"retry","validationCode":"// Pre-flight connectivity check\nresp, err := http.Get(\"https://status.notion.so\")\n// and verify egress: net.Dial(\"tcp\", \"api.notion.com:443\")","typeGuard":null,"tryCatchPattern":"err := client.Ping(ctx)\nif err != nil && strings.Contains(err.Error(), \"server error\") {\n    // transient 5xx: retry the whole operation after backoff\n    time.Sleep(time.Minute)\n    err = client.Ping(ctx)\n}","preventionTips":["Subscribe to the Notion status page for incident alerts","Retry syncs idempotently — the client already backs off 1/2/4s internally","Avoid custom baseURL mirrors unless they are reliable","Set generous HTTP timeouts (client uses 30s)"],"tags":["notion","http-5xx","server-error","retry","network"],"backgroundTag":"http-5xx-server-error","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}