{"record":{"id":"a6cdd0b95957da41","repo":"Hmbown/CodeWhale","slug":"runtime-api-request-failed-status-message","errorCode":null,"errorMessage":"Runtime API request failed (${status}): ${message}","messagePattern":"Runtime API request failed \\((.+?)\\): (.+?)","errorType":"http","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"integrations/bridge-core/src/lib.mjs","lineNumber":465,"sourceCode":"}\n\nexport function createRuntimeClient({ runtimeUrl, runtimeToken }) {\n  function authHeaders() {\n    return { authorization: `Bearer ${runtimeToken}` };\n  }\n\n  async function runtimeJson(route, options = {}) {\n    const response = await fetch(`${runtimeUrl}${route}`, {\n      method: options.method || \"GET\",\n      headers: {\n        ...(options.auth === false ? {} : authHeaders()),\n        ...(options.body ? { \"content-type\": \"application/json\" } : {})\n      },\n      body: options.body ? JSON.stringify(options.body) : undefined\n    });\n    const body = await readJsonSafe(response);\n    if (!response.ok) {\n      throw new Error(compactRuntimeError(response.status, body));\n    }\n    return body;\n  }\n\n  return { runtimeJson, authHeaders };\n}\n\nexport function compactRuntimeError(status, body) {\n  const message =\n    body?.error?.message ||\n    body?.message ||\n    (typeof body === \"string\" ? body : JSON.stringify(body));\n  return `Runtime API request failed (${status}): ${message}`;\n}\n\nexport function latestRunningTurn(detail) {\n  const turns = Array.isArray(detail?.turns) ? detail.turns : [];\n  for (let index = turns.length - 1; index >= 0; index -= 1) {","sourceCodeStart":447,"sourceCodeEnd":483,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/8880682c63083a91624de936797efa3ce9e498fd/integrations/bridge-core/src/lib.mjs#L447-L483","documentation":"bridge-core's runtimeJson() throws this whenever the codewhale runtime HTTP API answers non-2xx. compactRuntimeError() extracts body.error.message (or body.message) so the suffix is the server's own explanation; the number in parentheses is the HTTP status, e.g. `Runtime API request failed (401): invalid token`.","triggerScenarios":"401 when the bridge's auth headers do not match the runtime session; 404 when runtimeUrl points at the wrong port/path; 400 when the JSON body fails server-side validation; 5xx during runtime shutdown or crash.","commonSituations":"CODEWHALE_RUNTIME_URL stale after a restart (new port); token env copied from an older `codewhale web` run; a proxy in front of the runtime rewriting errors.","solutions":["Verify the runtime is up and the bridge's runtimeUrl/port matches it","Regenerate and re-pass the auth token env after the runtime restarts","Read the embedded server message - it usually names the exact bad field or auth problem","Health-check the runtime before dispatching traffic"],"exampleFix":"// before\nawait runtimeJson('/v1/threads', { method: 'POST', body: { prompt } });\n\n// after - check liveness first, fail with a clearer error\nconst probe = await fetch(runtimeUrl, { method: 'HEAD' }).catch(() => null);\nif (!probe || !probe.ok) {\n  throw new Error('codewhale runtime unreachable at ' + runtimeUrl);\n}\nawait runtimeJson('/v1/threads', { method: 'POST', body: { prompt } });","handlingStrategy":"try-catch","validationCode":"const probe = await fetch(runtimeUrl, { method: 'HEAD' }).catch(() => null);\nif (!probe || !probe.ok) {\n  throw new Error('codewhale runtime unreachable at ' + runtimeUrl);\n}","typeGuard":null,"tryCatchPattern":"try {\n  return await runtimeJson(route, options);\n} catch (err) {\n  const m = /^Runtime API request failed \\((\\d+)\\)/.exec(err.message);\n  if (m && m[1] === '401') { await refreshRuntimeAuth(); return retryOnce(); }\n  if (m && m[1] === '404') { throw new Error('runtime URL misrouted: ' + runtimeUrl + route); }\n  throw err;\n}","preventionTips":["Start/restart the runtime before the bridge and pass the fresh URL/token","Log the full compactRuntimeError message - it includes the server's reason","Health-check the runtime on bridge startup and on reconnect"],"tags":["runtime","http","bridge","network"],"backgroundTag":null,"analyzedSha":"8880682c63083a91624de936797efa3ce9e498fd","analyzedAt":"2026-08-16T11:31:27.956Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}