{"record":{"id":"e33fef697c2afaee","repo":"nexu-io/open-design","slug":"collab-cloud-error-status-code","errorCode":null,"errorMessage":"collab cloud error ${status} (${code})","messagePattern":"collab cloud error (.+?) \\((.+?)\\)","errorType":"exception","errorClass":"CollabCloudError","httpStatus":null,"severity":"error","filePath":"apps/daemon/src/integrations/collab-cloud.ts","lineNumber":106,"sourceCode":"  ): Promise<{ status: number; payload: T; etag: string | null }> {\n    const controller = new AbortController();\n    const timeout = setTimeout(() => controller.abort(), timeoutMs);\n    try {\n      const response = await fetchImpl(new URL(path, config!.baseUrl), {\n        method,\n        headers: authHeaders(extraHeaders),\n        ...(body === undefined ? {} : { body: JSON.stringify(body) }),\n        signal: controller.signal,\n      });\n      const etag = response.headers.get('etag');\n      if (response.status === 304) {\n        return { status: 304, payload: {} as T, etag };\n      }\n      const text = await response.text();\n      const payload = text ? JSON.parse(text) : {};\n      if (!response.ok) {\n        const code = typeof payload?.error === 'string' ? payload.error : 'unknown';\n        throw new CollabCloudError(response.status, code, payload?.message);\n      }\n      return { status: response.status, payload: payload as T, etag };\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n\n  return {\n    isConfigured(): boolean {\n      return true;\n    },\n\n    /** Register (idempotently upsert) a member's directory entry. */\n    async registerMember(\n      teamId: string,\n      memberId: string,\n      input: CollabCloudMemberRegistration,\n    ): Promise<CollabCloudMemberDirectoryEntry> {","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/nexu-io/open-design/blob/5be4028344c2eb4c667c5a97bda8f750c5597ef7/apps/daemon/src/integrations/collab-cloud.ts#L88-L124","documentation":"Thrown inside the client's request() helper as a CollabCloudError when the collab cloud HTTP response is not ok. It carries response.status, a code parsed from payload.error (or 'unknown'), and the upstream payload.message. The class is exported (CollabCloudError) with name set for instanceof checks, so callers can branch on status/code.","triggerScenarios":"Any collab cloud call (registerMember, pull, etc.) whose upstream PUT/GET returns 4xx/5xx, e.g. 401 (bad/missing OD_COLLAB_CLOUD_TOKEN), 403, 404 team/member path, or 5xx from the relay. Also triggered when the upstream returns a non-JSON body parsed into an object lacking an error field (code becomes 'unknown').","commonSituations":"Bearer token expired or rotated but OD_COLLAB_CLOUD_TOKEN not updated; team/member id mismatch against the relay's directory; relay/network returning 502/503; wrong baseUrl pointing at a different hub that rejects the token.","solutions":["Catch CollabCloudError by instanceof and branch on err.status / err.code: 401/403 → fix token, 404 → fix ids, 5xx → retry/back off.","Verify OD_COLLAB_CLOUD_TOKEN matches the hub's issued token and that baseUrl matches the relay.","For transient 5xx, wrap the call in a bounded retry with exponential backoff."],"exampleFix":"// before\nawait client.registerMember(teamId, memberId, input);\n\n// after\ntry {\n  await client.registerMember(teamId, memberId, input);\n} catch (err) {\n  if (err instanceof CollabCloudError && (err.status === 401 || err.status === 403)) {\n    // token/permission problem — surface to operator, do not retry\n  }\n  throw err;\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"import { CollabCloudError } from '../integrations/collab-cloud.js';\n\nfunction isCollabCloudError(err: unknown): err is CollabCloudError {\n  return err instanceof CollabCloudError;\n}\n\nfunction isAuthError(err: unknown): boolean {\n  return isCollabCloudError(err) && (err.status === 401 || err.status === 403);\n}","tryCatchPattern":"try {\n  await client.registerMember(teamId, memberId, input);\n} catch (err) {\n  if (err instanceof CollabCloudError) {\n    // branch on err.status and err.code; do not retry 4xx auth/not-found\n  }\n  throw err;\n}","preventionTips":["Always instanceof-check CollabCloudError before reading .status/.code.","Keep the token (OD_COLLAB_CLOUD_TOKEN) in sync with the hub.","Treat 5xx as transient (retry) and 4xx as permanent (fix config)."],"tags":["network","integration","http","collab-cloud"],"backgroundTag":null,"analyzedSha":"5be4028344c2eb4c667c5a97bda8f750c5597ef7","analyzedAt":"2026-08-12T12:03:58.812Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}