Hmbown/CodeWhale · error · RuntimeApiError

Runtime API request failed

Error message

Runtime API request failed (${response.status}) for ${method} ${path}

What it means

#rawRequest()'s fallback: when the runtime returns a non-OK status that is not a capability mismatch (i.e. not 404/405/501 with a declared capability), it throws RuntimeApiError including the status, method, and path. The error options carry the response body for diagnosis. It covers auth failures, bad requests, conflicts, and 5xx from the runtime.

Solutions

Read err.status and err.body from the RuntimeApiError to identify the exact server complaint.
For 401/403, fix the auth token/credentials supplied to the client.
For 5xx, retry with backoff and check runtime logs/health endpoint.
Ensure SDK and runtime versions are compatible.

Example fix

// before
await client.getFleetRun(id);
// after
try {
  await client.getFleetRun(id);
} catch (err) {
  if (err instanceof RuntimeApiError && err.status === 503) return retryWithBackoff();
  throw err;
}

Defensive patterns

Strategy: try-catch

Try / catch

try { return await call(); } catch (err) { if (err instanceof RuntimeApiError) { if (err.status === 429 || err.status >= 500) return retry(err); if (err.status === 401 || err.status === 403) return reauth(); } throw err; }

Prevention

Always log err.status and err.body from RuntimeApiError for diagnosis.
Refresh auth tokens before expiry; validate credentials at client construction.
Add retry-with-backoff for 5xx/429 and circuit-break repeated 4xx.

When it happens

Trigger: 401/403 from missing or invalid auth credentials; 400 from a malformed request built by your code; 409 conflicts; 500/502/503 from the runtime process or an upstream proxy.

Common situations: Expired or wrong API token; request body shape changed between SDK versions; runtime crashed or is being restarted behind a load balancer returning 502.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/445a57e807522ca4. Report an issue: GitHub.

Appendix: source

Thrown at npm/runtime-sdk/index.js:191

      headers.set("content-type", "application/json");
      init.body = JSON.stringify(options.body);
    }

    const response = await this.fetchImpl(new URL(path, this.baseUrl), init);
    if (response.ok) {
      return response;
    }

    const body = await readErrorBody(response);
    const errorOptions = { status: response.status, method, path, body };
    if (options.capability && [404, 405, 501].includes(response.status)) {
      throw new RuntimeCapabilityError(
        options.capability,
        `Runtime API capability '${options.capability}' is not available at ${method} ${path}`,
        errorOptions,
      );
    }
    throw new RuntimeApiError(
      `Runtime API request failed (${response.status}) for ${method} ${path}`,
      errorOptions,
    );
  }
}

export function createRuntimeClient(options = {}) {
  return new CodeWhaleRuntimeClient(options);
}

function normalizeBaseUrl(value) {
  return value.endsWith("/") ? value : `${value}/`;
}

function segment(value) {
  if (value === null || value === undefined || String(value).trim() === "") {
    throw new TypeError("Runtime API path segment must be a non-empty value");
  }

View on GitHub (pinned to 433685b202)