{"record":{"id":"664255e956179da1","repo":"authelia/authelia","slug":"failed-post-to-path-code-res-status-messa","errorCode":null,"errorMessage":"Failed POST to ${path}. Code: ${res.status}. Message: ${hasServiceError(res).message}","messagePattern":"Failed POST to (.+?)\\. Code: (.+?)\\. Message: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"web/src/services/Client.ts","lineNumber":34,"sourceCode":"): Promise<T | undefined> {\n    const res = await axios.put<ServiceResponse<T>>(path, body, { signal });\n\n    if (res.status !== 200 || hasServiceError(res).errored) {\n        throw new Error(`Failed PUT to ${path}. Code: ${res.status}. Message: ${hasServiceError(res).message}`);\n    }\n\n    return toData<T>(res);\n}\n\nexport async function PostWithOptionalResponse<T = undefined>(\n    path: string,\n    body?: any,\n    signal?: AbortSignal,\n): Promise<T | undefined> {\n    const res = await axios.post<ServiceResponse<T>>(path, body, { signal });\n\n    if (res.status !== 200 || hasServiceError(res).errored) {\n        throw new Error(`Failed POST to ${path}. Code: ${res.status}. Message: ${hasServiceError(res).message}`);\n    }\n\n    return toData<T>(res);\n}\n\nexport async function PostWithOptionalResponseRateLimited<T = undefined>(\n    path: string,\n    body?: any,\n    signal?: AbortSignal,\n): Promise<RateLimitedData<T> | undefined> {\n    const res = await axios.post<ServiceResponse<T>>(path, body, {\n        signal,\n        validateStatus: validateStatusTooManyRequests,\n    });\n\n    if (res.status !== 200 || hasServiceError(res).errored) {\n        if (res.status === 429) {\n            return toDataRateLimited<T>(res);","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/authelia/authelia/blob/c883b8d3d8f278d61e2627e317be2e9ddc09e15b/web/src/services/Client.ts#L16-L52","documentation":"Generic failure thrown by PostWithOptionalResponse in Authelia's API client after a POST request. Axios's default validateStatus rejects non-2xx as AxiosError first, so this message fires only for 2xx-but-not-200 responses (e.g. 204) or 200 responses whose body has status 'KO' per hasServiceError. The thrown text embeds path, HTTP code, and the server's message.","triggerScenarios":"A POST to endpoints such as /api/firstfactor, /api/logout, or /api/reset-password/identity/start that returns 200 with {status:'KO', message:'...'} (bad credentials shape, banned user, rejected operation) or a non-200 2xx like 204.","commonSituations":"Submitting an invalid or locked-out first-factor login; backend validation rejecting a password reset start; a proxy or middleware answering 204; custom backend endpoints not following the OK/KO response convention.","solutions":["Read the 'Message:' segment - it is the server's own explanation (e.g. 'invalid credentials', 'user is banned')","Confirm the request payload matches the endpoint's expected schema before retrying","Check backend logs for the matching POST to see the KO reason","Ensure custom endpoints return {status:'OK'} / {status:'KO'} with HTTP 200","Align SPA and backend versions after upgrades"],"exampleFix":"// before\nawait PostWithOptionalResponse('/api/logout', undefined, signal);\n\n// after\ntry {\n    await PostWithOptionalResponse('/api/logout', undefined, signal);\n} catch (err) {\n    if (err instanceof Error && err.message.startsWith('Failed POST to ')) {\n        notify(extractServerMessage(err.message)); // service-level KO\n        return;\n    }\n    throw err; // transport-level failure (non-2xx, network) handled upstream\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isServiceErrorResponse(body: unknown): body is { status: 'KO'; message: string } {\n    return typeof body === 'object' && body !== null && (body as Record<string, unknown>).status === 'KO';\n}","tryCatchPattern":"try {\n    await PostWithOptionalResponse(path, body, signal);\n} catch (err) {\n    if (err instanceof Error && err.message.startsWith('Failed POST to ')) {\n        handleServiceError(err.message);\n        return;\n    }\n    if (axios.isAxiosError(err)) {\n        handleTransportError(err);\n        return;\n    }\n    throw err;\n}","preventionTips":["Validate request payloads against the endpoint schema before submitting","Surface the embedded server message to users instead of retrying blindly","Never wrap this call in a bare catch that swallows the message"],"tags":["http","api-client","post","service-error","authelia"],"backgroundTag":null,"analyzedSha":"c883b8d3d8f278d61e2627e317be2e9ddc09e15b","analyzedAt":"2026-08-15T21:33:05.930Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}