{"record":{"id":"cceaaf3fbeebb720","repo":"n8n-io/n8n","slug":"request-failed-response-status","errorCode":null,"errorMessage":"Request failed (${response.status})","messagePattern":"Request failed \\((.+?)\\)","errorType":"exception","errorClass":"ApiError","httpStatus":null,"severity":"error","filePath":"packages/@n8n/cli/src/client.ts","lineNumber":153,"sourceCode":"\t\t\t\t`Connection error: ${msg}. Check the URL and ensure the instance is running.`,\n\t\t\t);\n\t\t}\n\n\t\tthis.debug?.(`← ${response.status} ${response.statusText} (${Date.now() - start}ms)`);\n\n\t\tif (!response.ok) {\n\t\t\tconst errorBody = await this.readBody(response);\n\t\t\tconst message =\n\t\t\t\ttypeof errorBody === 'object' && errorBody !== null && 'message' in errorBody\n\t\t\t\t\t? String((errorBody as Record<string, unknown>).message)\n\t\t\t\t\t: `Request failed (${response.status})`;\n\t\t\tconst hint =\n\t\t\t\tresponse.status === 401\n\t\t\t\t\t? \"Check your API key. Run 'n8n-cli config set-api-key <key>' or set N8N_API_KEY.\"\n\t\t\t\t\t: response.status === 404\n\t\t\t\t\t\t? 'Resource not found. Verify the ID is correct.'\n\t\t\t\t\t\t: undefined;\n\t\t\tthrow new ApiError(response.status, message, hint, errorBody);\n\t\t}\n\n\t\toptions.onResponse?.(response);\n\n\t\tif (response.status === 204) {\n\t\t\treturn undefined as T;\n\t\t}\n\n\t\tif (options.responseType === 'binary') {\n\t\t\treturn Buffer.from(await response.arrayBuffer()) as T;\n\t\t}\n\n\t\treturn (await this.readBody(response)) as T;\n\t}\n\n\tprivate async readBody(response: Response): Promise<unknown> {\n\t\tconst contentType = response.headers.get('content-type') ?? '';\n\t\treturn contentType.includes('application/json') ? await response.json() : await response.text();","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/cli/src/client.ts#L135-L171","documentation":"Thrown by N8nClient.request() when response.ok is false (status >= 400) AND the error response body lacks a recognizable 'message' field. The fallback message includes the raw status code. When the server returns a structured {message: '...'} body, that message is used instead — this fires only when the body is unstructured or non-JSON.","triggerScenarios":"Any API call returns 4xx/5xx with a non-JSON body or a JSON body without a message field: 500 with an HTML error page, 502/504 from a reverse proxy, 413 with empty body, 429 with a plain-text rate-limit notice.","commonSituations":"Invalid resource ID (404 but server returns no message), server crash (500 with HTML), rate limiting (429), API version mismatch, payload too large.","solutions":["Check ApiError.statusCode and ApiError.hint for guidance","For 401: set a valid API key via 'n8n-cli config set-api-key <key>' or N8N_API_KEY","For 404: verify the resource ID exists and the endpoint path is correct","For 5xx: check the n8n server logs for the underlying error","Inspect ApiError.details for the raw error body"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"import { ApiError } from './client';\n\nfunction isApiError(e: unknown): e is ApiError {\n  return e instanceof ApiError;\n}","tryCatchPattern":"try {\n  return await client.getWorkflow(id);\n} catch (e) {\n  if (e instanceof ApiError) {\n    switch (e.statusCode) {\n      case 401: throw new Error('API key invalid. Run: n8n-cli config set-api-key <key>');\n      case 404: throw new Error(`Workflow ${id} not found`);\n      case 429: throw new Error('Rate limited. Retry later.');\n      default: throw new Error(`API error ${e.statusCode}: ${e.message}`);\n    }\n  }\n  throw e;\n}","preventionTips":["Keep the API key current and validate it at startup","Verify resource IDs exist before making calls when possible","Handle specific status codes (401, 404, 429, 5xx) with appropriate recovery logic"],"tags":["http","cli","api"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}