{"record":{"id":"48c0a0e6e0fa7fa7","repo":"mastra-ai/mastra","slug":"http-error-status-response-status-json-st","errorCode":null,"errorMessage":"HTTP error! status: ${response.status} - ${JSON.stringify(parsedBody) | errorBody}","messagePattern":"HTTP error! status: (.+?) - (.+?)","errorType":"http","errorClass":"MastraClientError","httpStatus":null,"severity":"error","filePath":"client-sdks/client-js/src/resources/base.ts","lineNumber":73,"sourceCode":"          signal: this.options.abortSignal,\n          credentials: options.credentials ?? credentials,\n          body:\n            options.body instanceof FormData ? options.body : options.body ? JSON.stringify(options.body) : undefined,\n        });\n\n        if (!response.ok) {\n          const errorBody = await response.text();\n          let parsedBody: unknown;\n          let errorMessage = `HTTP error! status: ${response.status}`;\n          try {\n            parsedBody = JSON.parse(errorBody);\n            errorMessage += ` - ${JSON.stringify(parsedBody)}`;\n          } catch {\n            if (errorBody) {\n              errorMessage += ` - ${errorBody}`;\n            }\n          }\n          throw new MastraClientError(response.status, response.statusText, errorMessage, parsedBody);\n        }\n\n        if (options.stream) {\n          return response as unknown as T;\n        }\n\n        const data = await response.json();\n        return data as T;\n      } catch (error) {\n        lastError = error as Error;\n\n        // Don't retry 4xx client errors - they won't resolve with retries\n        const status = (error as Error & { status?: number }).status;\n        if (status !== undefined && status >= 400 && status < 500) {\n          throw error;\n        }\n\n        if (attempt === retries) {","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/client-js/src/resources/base.ts#L55-L91","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconst task = await client.getTask(taskId);\n\n// after\ntry {\n  const task = await client.getTask(taskId);\n} catch (e) {\n  if (e instanceof MastraClientError && e.status === 404) {\n    console.error(`Task ${taskId} not found`);\n  } else throw e;\n}","handlingStrategy":"try-catch","validationCode":"if (!baseUrl) throw new Error('MastraClient baseUrl required');\nif (!apiKey) console.warn('No API key configured — expect 401 MastraClientError');","typeGuard":"function isMastraClientError(e: unknown): e is MastraClientError {\n  return e instanceof MastraClientError || (typeof e === 'object' && e !== null && 'status' in e && 'statusText' in e);\n}","tryCatchPattern":"try {\n  const result = await client.getTask(taskId);\n} catch (e) {\n  if (isMastraClientError(e)) {\n    switch (e.status) {\n      case 401: fixCredentials(); break;\n      case 404: handleNotFound(taskId); break;\n      default: if (e.status >= 500) scheduleRetry();\n    }\n  } else throw e;\n}","preventionTips":["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"],"tags":["http","network","client-js"],"backgroundTag":"http-error-response","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}