mastra-ai/mastra · error · MastraClientError

HTTP error! status: ${response.status} - ${JSON.stringify(pa

Error message

HTTP error! status: ${response.status} - ${JSON.stringify(parsedBody) | errorBody}

What it means

A MastraClientError thrown by the shared request() helper in base.ts when the server returns a non-OK HTTP status. The message embeds the status code, status text, and the parsed (or raw) error body returned by the server, giving the actual server-side failure reason.

Source

Thrown at client-sdks/client-js/src/resources/base.ts:73

          signal: this.options.abortSignal,
          credentials: options.credentials ?? credentials,
          body:
            options.body instanceof FormData ? options.body : options.body ? JSON.stringify(options.body) : undefined,
        });

        if (!response.ok) {
          const errorBody = await response.text();
          let parsedBody: unknown;
          let errorMessage = `HTTP error! status: ${response.status}`;
          try {
            parsedBody = JSON.parse(errorBody);
            errorMessage += ` - ${JSON.stringify(parsedBody)}`;
          } catch {
            if (errorBody) {
              errorMessage += ` - ${errorBody}`;
            }
          }
          throw new MastraClientError(response.status, response.statusText, errorMessage, parsedBody);
        }

        if (options.stream) {
          return response as unknown as T;
        }

        const data = await response.json();
        return data as T;
      } catch (error) {
        lastError = error as Error;

        // Don't retry 4xx client errors - they won't resolve with retries
        const status = (error as Error & { status?: number }).status;
        if (status !== undefined && status >= 400 && status < 500) {
          throw error;
        }

        if (attempt === retries) {

View on GitHub (pinned to 75dd419e61)

Solutions

Read the status code and parsedBody in the error — it contains the server's actual error message.
For 401/403, fix credentials/API key configuration passed to MastraClient.
For 404, verify the agentId/taskId/workflowId exists on the target server and base URL is correct.
For 5xx, check Mastra server logs; retry with backoff for transient 502/503.

Example fix

// before
const task = await client.getTask(taskId);

// after
try {
  const task = await client.getTask(taskId);
} catch (e) {
  if (e instanceof MastraClientError && e.status === 404) {
    console.error(`Task ${taskId} not found`);
  } else throw e;
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (!baseUrl) throw new Error('MastraClient baseUrl required');
if (!apiKey) console.warn('No API key configured — expect 401 MastraClientError');

Type guard

function isMastraClientError(e: unknown): e is MastraClientError {
  return e instanceof MastraClientError || (typeof e === 'object' && e !== null && 'status' in e && 'statusText' in e);
}

Try / catch

try {
  const result = await client.getTask(taskId);
} catch (e) {
  if (isMastraClientError(e)) {
    switch (e.status) {
      case 401: fixCredentials(); break;
      case 404: handleNotFound(taskId); break;
      default: if (e.status >= 500) scheduleRetry();
    }
  } else throw e;
}

Prevention

Always read e.status and the error body — the server reason is embedded
Validate IDs (agentId/taskId) exist before calling
Configure baseUrl and auth explicitly, not from ambient env
Pin client and server versions to avoid endpoint mismatches

When it happens

Trigger: Any client call routed through request() — agentCard, response, sendMessage, sendStreamingMessage, getTask, cancelTask — where response.ok is false (client-sdks/client-js/src/resources/base.ts:73). Includes 401 auth failures, 404 unknown agent/task IDs, 500 server errors.

Common situations: Wrong base URL or API key (401/403); requesting a taskId or agent that does not exist (404); server bug producing 500; version mismatch where the client calls an endpoint the server does not expose.

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 mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/48c0a0e6e0fa7fa7. Report an issue: GitHub.