mastra-ai/mastra · error · ApiCliError

HTTP_ERROR

HTTP_ERROR

Error message

HTTP_ERROR: Request failed with status ${response.status}

What it means

requestApi in the CLI's API client performs an HTTP request and throws ApiCliError with code 'HTTP_ERROR' whenever the response status is not ok (response.ok is false, i.e. 4xx/5xx). The message embeds the numeric status and the error carries `status` and the parsed response `body` as details. This is the CLI's generic wrapper for any non-2xx response from the Mastra API.

Source

Thrown at packages/cli/src/commands/api/client.ts:37

  try {
    const { queryInput, bodyInput } = splitInput(options.descriptor, options.input);
    const url = buildUrl(options.baseUrl, options.descriptor.path, options.pathParams, queryInput, options.apiPrefix);
    const init: RequestInit = {
      method: options.descriptor.method,
      headers: { ...options.headers },
      signal: controller.signal,
    };

    if (options.descriptor.method !== 'GET' && bodyInput) {
      init.headers = { 'content-type': 'application/json', ...init.headers };
      init.body = JSON.stringify(bodyInput);
    }

    const response = await fetch(url, init);
    const body = await parseResponse(response);

    if (!response.ok) {
      throw new ApiCliError('HTTP_ERROR', `Request failed with status ${response.status}`, {
        status: response.status,
        body,
      });
    }

    return body;
  } catch (error) {
    if (error instanceof Error && error.name === 'AbortError') {
      throw new ApiCliError('REQUEST_TIMEOUT', `Request timed out after ${options.timeoutMs}ms`, {
        timeoutMs: options.timeoutMs,
      });
    }
    throw toApiCliError(error);
  } finally {
    clearTimeout(timeout);
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read `error.details.status` and `error.details.body` — they tell you exactly what failed; re-authenticate if 401/403
2. Verify the configured base URL / environment (e.g. `mastra login` or env config) matches your deployment
3. Update the CLI to the latest version to avoid route/schema mismatches (404s from version drift)
4. For 5xx, retry with backoff and check the Mastra status/incident channels
5. Inspect the body field for validation details if the status is 400/422 and fix the request payload

Example fix

// before
const res = await client.requestApi('/registry/manifest'); // 401 HTTP_ERROR
// after
await cli.login(); // refresh credentials first
const res = await client.requestApi('/registry/manifest');
// or defensively
try {
  const res = await client.requestApi(url);
} catch (e) {
  if (e.code === 'HTTP_ERROR' && e.details.status === 401) await reauthenticate();
  throw e;
}

// Before calling, ensure credentials and base URL are present
if (!process.env.MASTRA_API_KEY) throw new Error('MASTRA_API_KEY is not set');
new URL(path, baseUrl); // throws early on malformed base URL

import { ApiCliError } from './errors';
function isHttpCliError(e: unknown): e is ApiCliError & { details: { status: number; body: unknown } } {
  return e instanceof ApiCliError && e.code === 'HTTP_ERROR' && typeof (e.details as any)?.status === 'number';
}

try {
  const body = await client.requestApi(url, init);
} catch (e) {
  if (isHttpCliError(e)) {
    const { status, body } = e.details;
    if (status === 401 || status === 403) await reauthenticate();
    else if (status >= 500) await retryWithBackoff(() => client.requestApi(url, init));
    else console.error('Request rejected:', status, body);
    return;
  }
  throw e;
}

When it happens

Trigger: Any fetch from `requestApi` (used by fetchSchemaManifest and executeDescriptor) where the server responds 4xx/5xx: 401/403 (bad or missing auth token), 404 (wrong base URL or unknown route/version), 422 (bad request payload), 5xx (server outage).

Common situations: Stale or missing MASTRA_API_KEY / login session, pointing the CLI at the wrong environment URL, API version drift (CLI older than server routes), corporate proxy intercepting requests, or the server returning 500 during an incident.

Related errors

• skill_invocation_failed
• REQUEST_TIMEOUT
• Failed to fetch templates: ${response.statusText}
• Failed to load templates. Please check your internet connect
• Registration failed with status ${response.status}: ${respon

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/f4abf176ef0496c6. Report an issue: GitHub.