{"record":{"id":"4eccdb3a3fb16fee","repo":"can1357/oh-my-pi","slug":"http-response-status-text-suffix","errorCode":null,"errorMessage":"HTTP ${response.status}: ${text}${suffix}","messagePattern":"HTTP (.+?): (.+?)(.+?)","errorType":"http","errorClass":"MCPTransportError","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/mcp/transports/http.ts","lineNumber":481,"sourceCode":"\n\t\t\t// Check for session ID in response\n\t\t\tconst newSessionId = response.headers.get(\"Mcp-Session-Id\");\n\t\t\tif (newSessionId) {\n\t\t\t\tthis.#sessionId = newSessionId;\n\t\t\t}\n\n\t\t\tif (!response.ok) {\n\t\t\t\tconst text = await response.text();\n\t\t\t\tconst wwwAuthenticate = response.headers.get(\"WWW-Authenticate\");\n\t\t\t\tconst mcpAuthServer = response.headers.get(\"Mcp-Auth-Server\");\n\t\t\t\tconst authHints = [\n\t\t\t\t\twwwAuthenticate ? `WWW-Authenticate: ${wwwAuthenticate}` : null,\n\t\t\t\t\tmcpAuthServer ? `Mcp-Auth-Server: ${mcpAuthServer}` : null,\n\t\t\t\t]\n\t\t\t\t\t.filter(Boolean)\n\t\t\t\t\t.join(\"; \");\n\t\t\t\tconst suffix = authHints ? ` [${authHints}]` : \"\";\n\t\t\t\tthrow new MCPTransportError({\n\t\t\t\t\ttransport: \"http\",\n\t\t\t\t\tstage,\n\t\t\t\t\tfailure: \"http_status\",\n\t\t\t\t\tmessage: `HTTP ${response.status}: ${text}${suffix}`,\n\t\t\t\t\tretryable: response.status === 404 || response.status === 502 || response.status === 503,\n\t\t\t\t\tcode: response.status,\n\t\t\t\t\ttraceId,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst contentType = response.headers.get(\"Content-Type\") ?? \"\";\n\n\t\t\t// Handle SSE response\n\t\t\tif (contentType.includes(\"text/event-stream\")) {\n\t\t\t\treturn this.#parseSSEResponse<T>(response, id, options);\n\t\t\t}\n\n\t\t\tstage = \"decode\";","sourceCodeStart":463,"sourceCodeEnd":499,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/mcp/transports/http.ts#L463-L499","documentation":"The MCP JSON-RPC POST received a non-2xx HTTP status. The transport reads the response body and any auth hint headers (WWW-Authenticate, Mcp-Auth-Server), appends them in brackets, and throws an MCPTransportError with failure: http_status and the status as code. Only 404/502/503 are marked retryable.","triggerScenarios":"Server responds 4xx/5xx to a JSON-RPC POST: 401/403 (auth rejected), 404 (wrong URL or evicted session), 429 (rate limit), 5xx (server fault); auth hints included when the server supplies WWW-Authenticate or Mcp-Auth-Server.","commonSituations":"Expired/invalid API keys; hitting the wrong endpoint path; Mcp-Session-Id expired after server restart; server overloaded or down; rate limiting from aggressive polling.","solutions":["Read the status and bracketed auth hints: 401/403 → fix credentials or wire onAuthError for automatic refresh; 404 → verify URL and reconnect for a new session; 429 → back off; 5xx → check server health","Retry if status is 404/502/503 (marked retryable), otherwise correct the underlying cause first","Confirm the MCP endpoint URL matches the server's advertised path and protocol version","Inspect traceId against server logs to correlate the rejected request"],"exampleFix":"// before\nawait transport.request(\"tools/list\"); // throws HTTP 404 after server restart evicted session\n// after\nawait transport.connect(); // re-establish session, gets fresh Mcp-Session-Id\nawait transport.request(\"tools/list\");","handlingStrategy":"try-catch","validationCode":"// Pre-flight the endpoint and credentials:\nconst res = await fetch(url, { method: \"OPTIONS\" });\nif (res.status === 401 || res.status === 403) throw new Error(\"credentials invalid before any request\");","typeGuard":null,"tryCatchPattern":"try {\n  await transport.request(method, params);\n} catch (err) {\n  if (err instanceof MCPTransportError && err.failure === \"http_status\") {\n    if (err.code === 401 || err.code === 403) await refreshAuth();\n    else if (err.retryable) await backoffAndRetry();\n    else throw err;\n  } else throw err;\n}","preventionTips":["Wire onAuthError for automatic 401/403 refresh","Reconnect after server restarts to obtain a fresh Mcp-Session-Id","Respect 429 with exponential backoff","Confirm endpoint URL and protocol version at onboarding"],"tags":["mcp","http","json-rpc","api"],"backgroundTag":"http-status-error","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}