thedotmack/claude-mem · error · ServerClientError

http_error

http_error

Error message

Server ${method} ${path} returned ${response.status}: ${truncate(text, 200)}

What it means

Thrown when the server responded, but with a non-2xx status. The response body (truncated to 200 chars) is embedded in the message and the HTTP status is attached to the error. Code is 'http_error'. This surfaces server-side rejections such as 401 unauthorized, 404 unknown route, or 500 internal errors.

Solutions

  1. Read the status and body in the message: 401/403 → fix CLAUDE_MEM_SERVER_API_KEY; 404 → align client and server versions.
  2. For 5xx, check server logs for the underlying exception and retry after fixing.
  3. Handle the error by inspecting err.status for programmatic branching (e.g. skip on 404).
  4. Re-run the server upgrade if the endpoint was added in a newer version.

Example fix

// before
await client.recordEvent(event); // throws http_error 404

// after
try {
  await client.recordEvent(event);
} catch (e) {
  if (e instanceof ServerClientError && e.code === 'http_error' && e.status === 404) {
    // fall back to local processing; server does not support this endpoint
  } else throw e;
}
Defensive patterns

Strategy: try-catch

Try / catch

try {
  await client.searchObservations(q);
} catch (e) {
  if (e instanceof ServerClientError && e.code === 'http_error') {
    switch (e.status) {
      case 401: case 403: /* refresh API key */ break;
      case 404: /* fall back to local mode */ break;
      default: /* log and retry later */
    }
  } throw e;
}

Prevention

When it happens

Trigger: Any ServerClient request where response.ok is false — e.g. revoked/wrong API key (401), hitting a server version lacking the endpoint (404), or a server-side exception (5xx).

Common situations: API key rotated or invalid, client and server version mismatch after an upgrade, or the server crashing while handling a malformed payload.

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 thedotmack/claude-mem@d8bc9755e7 (2026-09-17). Data as JSON: /api/errors/e5c07bab02d04f14. Report an issue: GitHub.

Appendix: source

Thrown at src/services/hooks/server-client.ts:390

      init.body = JSON.stringify(body);
    }

    let response: Response;
    try {
      response = await fetchWithTimeout(url, init, this.timeoutMs);
    } catch (error: unknown) {
      const message = error instanceof Error ? error.message : String(error);
      const isTimeout = /timed out|timeout/i.test(message);
      throw new ServerClientError(
        isTimeout ? 'timeout' : 'transport',
        `Server ${method} ${path} failed: ${message}`,
        { cause: error },
      );
    }

    if (!response.ok) {
      const text = await response.text().catch(() => '');
      throw new ServerClientError(
        'http_error',
        `Server ${method} ${path} returned ${response.status}: ${truncate(text, 200)}`,
        { status: response.status },
      );
    }

    const text = await response.text();
    if (!text || text.length === 0) {
      // Endpoints we call always return JSON; a body-less success is unusual
      // but not fatal — return undefined-shaped object.
      return {} as T;
    }
    try {
      return JSON.parse(text) as T;
    } catch (error: unknown) {
      const err = error instanceof Error ? error : new Error(String(error));
      throw new ServerClientError(
        'invalid_response',

View on GitHub (pinned to d8bc9755e7)