{"record":{"id":"286525c3505c9e1d","repo":"paperclipai/paperclip","slug":"err-reasoncode","errorCode":"err.reasonCode","errorMessage":"err.message","messagePattern":"err\\.message","errorType":"http","errorClass":"ToolGatewayHttpError","httpStatus":null,"severity":"error","filePath":"server/src/services/tool-gateway.ts","lineNumber":10890,"sourceCode":"    async listRuntimeSlots(companyId?: string) {\n      return runtimeSupervisor.listSlots(companyId);\n    },\n\n    async stopRuntimeSlot(input: {\n      companyId: string;\n      slotId: string;\n      actor?: { agentId?: string | null; runId?: string | null };\n    }) {\n      try {\n        return await runtimeSupervisor.stopSlot({\n          companyId: input.companyId,\n          slotId: input.slotId,\n          agentId: input.actor?.agentId ?? null,\n          runId: input.actor?.runId ?? null,\n        });\n      } catch (err) {\n        if (err instanceof ToolRuntimeSupervisorError) {\n          throw new ToolGatewayHttpError(\n            err.status,\n            err.message,\n            err.reasonCode,\n            err.details,\n          );\n        }\n        throw err;\n      }\n    },\n\n    async restartRuntimeSlot(input: {\n      companyId: string;\n      slotId: string;\n      actor?: { agentId?: string | null; runId?: string | null };\n    }) {\n      try {\n        return await runtimeSupervisor.restartSlot({\n          companyId: input.companyId,","sourceCodeStart":10872,"sourceCodeEnd":10908,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/server/src/services/tool-gateway.ts#L10872-L10908","documentation":"During slot acquisition for a gateway tool call, a ToolRuntimeSupervisorError thrown by the runtime supervisor is converted into a ToolGatewayHttpError preserving its HTTP status, message, reasonCode, and details. This surfaces supervisor-level slot failures (e.g. capacity limits, stuck slots, restart storms) as structured HTTP errors to the caller.","triggerScenarios":"Calling executeGatewayTool when the supervisor cannot allocate/restart the runtime slot: company slot limit (maxCompanySlots) reached, host slot limit reached, restart storm detected, slot stuck beyond stuckSlotMs, or the runtime process failed to start.","commonSituations":"A company runs more than maxCompanySlots (4) concurrent tool connections; the runtime binary crashes repeatedly triggering backoff/storm protection; an idle slot expired between check and use; deployment mode/exposure misconfiguration.","solutions":["Inspect err.reasonCode and err.status to identify the supervisor failure (capacity vs startup vs stuck slot).","Stop unused slots or wait for idleTtlMs (1s default) / restart backoff to elapse, then retry the tool call.","Raise maxCompanySlots/maxHostSlots in ToolRuntimeSupervisorOptions if limits are legitimately too low.","Check the tool access audit events (toolAccessAuditEvents) for the restart/backoff history of the slot."],"exampleFix":"// before\nawait executeGatewayTool(input); // throws ToolGatewayHttpError (supervisor)\n// after\ntry {\n  await executeGatewayTool(input);\n} catch (e) {\n  if (e instanceof ToolGatewayHttpError && e.reasonCode === \"slot_capacity\") {\n    await stopIdleSlots(companyId);\n    return executeGatewayTool(input); // retry after capacity freed\n  }\n  throw e;\n}","handlingStrategy":"retry","validationCode":"const slots = await getCompanySlots(companyId);\nif (slots.filter(s => [\"starting\",\"running\",\"idle\"].includes(s.status)).length >= 4) await stopIdleSlots(companyId);","typeGuard":"function isSupervisorGatewayError(e: unknown): e is ToolGatewayHttpError {\n  return e instanceof ToolGatewayHttpError && typeof e.reasonCode === \"string\" && e.reasonCode.startsWith(\"slot\");\n}","tryCatchPattern":"try {\n  return await executeGatewayTool(input);\n} catch (e) {\n  if (isSupervisorGatewayError(e) && [429, 503].includes(e.status)) {\n    await backoffRetry(() => executeGatewayTool(input), { attempts: 3, baseMs: 1000 });\n  }\n  throw e;\n}","preventionTips":["Monitor active slot counts per company against maxCompanySlots and free idle slots proactively.","Set explicit idleTtlMs suited to your workload instead of relying on the 1s default.","Alert on restart-storm reason codes; they usually mean the runtime binary is crashing."],"tags":["http","runtime","capacity"],"backgroundTag":"http-error-response","analyzedSha":"3f1d897a7c018d76563a21c6e39c3c9b03933622","analyzedAt":"2026-09-18T08:03:59.046Z","contentChangedAt":"2026-09-18T08:03:59.046Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}