{"record":{"id":"8ae51ffac18f671a","repo":"Hmbown/CodeWhale","slug":"options-capability","errorCode":"${options.capability}","errorMessage":"Runtime API capability '${options.capability}' is not available at ${method} ${path}","messagePattern":"Runtime API capability '(.+?)' is not available at (.+?) (.+?)","errorType":"error_code","errorClass":"RuntimeCapabilityError","httpStatus":null,"severity":"error","filePath":"npm/runtime-sdk/index.js","lineNumber":185,"sourceCode":"      headers.set(\"authorization\", `Bearer ${this.token}`);\n    }\n    const init = { method, headers };\n    if (options.signal) init.signal = options.signal;\n    if (options.redirect) init.redirect = options.redirect;\n    if (options.body !== undefined) {\n      headers.set(\"content-type\", \"application/json\");\n      init.body = JSON.stringify(options.body);\n    }\n\n    const response = await this.fetchImpl(new URL(path, this.baseUrl), init);\n    if (response.ok) {\n      return response;\n    }\n\n    const body = await readErrorBody(response);\n    const errorOptions = { status: response.status, method, path, body };\n    if (options.capability && [404, 405, 501].includes(response.status)) {\n      throw new RuntimeCapabilityError(\n        options.capability,\n        `Runtime API capability '${options.capability}' is not available at ${method} ${path}`,\n        errorOptions,\n      );\n    }\n    throw new RuntimeApiError(\n      `Runtime API request failed (${response.status}) for ${method} ${path}`,\n      errorOptions,\n    );\n  }\n}\n\nexport function createRuntimeClient(options = {}) {\n  return new CodeWhaleRuntimeClient(options);\n}\n\nfunction normalizeBaseUrl(value) {\n  return value.endsWith(\"/\") ? value : `${value}/`;","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/433685b2024e7bc4c99e1e2e326bcad39b4d9d65/npm/runtime-sdk/index.js#L167-L203","documentation":"#rawRequest() maps HTTP 404, 405, and 501 responses to RuntimeCapabilityError when the request declared a capability (e.g. thread_event_stream, fleet endpoints). It signals that the connected runtime does not offer that API capability at the requested method/path. This is a version/feature mismatch, not a generic HTTP failure.","triggerScenarios":"Calling a method like threadEvents, fleetEvents, getFleetRun, or listFleetWorkers against a runtime that returns 404/405/501 for that endpoint — e.g. fleet APIs invoked against a single-node runtime, or newer SDK methods against an older runtime.","commonSituations":"SDK and runtime version skew; feature flags disabled server-side; pointing the SDK at a gateway that only proxies a subset of routes.","solutions":["Check err.code (the capability name) and upgrade the runtime to one that supports it.","Guard feature usage with try/catch on RuntimeCapabilityError and degrade gracefully.","Verify the request path/method matches the SDK's expected API surface (no custom base path rewriting in your proxy)."],"exampleFix":"// before\nconst runs = await client.listFleetWorkers(runId);\n// after\ntry {\n  const runs = await client.listFleetWorkers(runId);\n} catch (err) {\n  if (err instanceof RuntimeCapabilityError) return fallbackLocalWorkers();\n  throw err;\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"const isCapabilityMissing = (err) => err instanceof RuntimeCapabilityError;","tryCatchPattern":"try { return await client.listFleetWorkers(runId); } catch (err) { if (err instanceof RuntimeCapabilityError) { warn(\"runtime lacks capability \" + err.code); return []; } throw err; }","preventionTips":["Version-gate feature usage: only call fleet/thread-stream APIs against runtimes that advertise them.","Map err.code values to feature flags in a central compatibility table.","Run an integration check against each deployed runtime version before enabling dependent features."],"tags":["capability","http-404","version-compatibility","runtime-api"],"backgroundTag":"api-error-response","analyzedSha":"433685b2024e7bc4c99e1e2e326bcad39b4d9d65","analyzedAt":"2026-09-15T12:24:24.634Z","contentChangedAt":"2026-09-15T12:24:24.634Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}