@@ -0,0 +1,12 @@
+---
+'@object-ui/app-shell': patch
+---
+
+fix(console): a flow-backed api action shows the run's refusal, not the engine's node chain
+
+Clause-②: no
+Metadata-protocol: none
+
+A `type: 'api'` action whose target is a declared `type: 'flow'` endpoint gets the trigger door's `400 FLOW_FAILED` when the run fails. The record page's action menu and the list and toolbar actions showed that envelope's message, so a member refused on the flow's write read text like `Node 'recalc_each' failed: map … subflow … update_record(showcase_task) failed: …`. Both api handlers now read the answer by the rule a screen flow already uses: the flow's own `errorMessage`, then the producer-marked `userMessage`, then the refusal the write met (`innerRefusal`), rendered as the record form renders it (a permission denial reads the form's permission line in the console's language), and only then the message. Any other error answer reads as before.
+
+A failure inside a `map` item or a `subflow` reaches this door with no `innerRefusal` until the engine carries it out of those nodes, so that chain still shows the message.
@@ -0,0 +1,141 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * objectstack#27487 — a `type: 'api'` action whose target is a declared
+ * `type: 'flow'` endpoint shows the run's inner refusal, not the node chain.
+ *
+ * The endpoint answers a failed run with the trigger door's `400 FLOW_FAILED`
+ * (`error.details.innerRefusal` included). The shared console runtime's
+ * `apiHandler` used to toast that envelope's `message`, so a member refused on
+ * a flow's `update_record` read `Node '…' failed: update_record(…) failed: …`.
+ * It now reads the envelope through `apiActionFailureMessage`, in the host's
+ * active language.
+ *
+ * CONTROL: a 4xx that is not `FLOW_FAILED` still reads its own message.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { builtInLocales, registerBuiltInLocales } from '@object-ui/i18n/locales';
+
+vi.mock('react-router-dom', () => ({ useNavigate: () => vi.fn() }));
+
+const authFetchSpy = vi.fn();
+vi.mock('@object-ui/auth', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useAuth: () => ({ user: { id: 'u1', name: 'User', image: null }, activeOrganization: null }),
+  createAuthenticatedFetch: () => authFetchSpy,
+}));
+
+vi.mock('@object-ui/i18n', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useObjectLabel: () => ({
+    fieldLabel: (_o: any, _n: any, l: any) => l,
+    fieldOptionLabel: (_o: any, _f: any, _v: any, l: any) => l,
+    actionParamText: (_o: any, _a: any, _p: any, _attr: any, fallback: any) => fallback,
+    actionParamOptionLabel: (_o: any, _a: any, _p: any, _v: any, fallback: any) => fallback,
+    actionDescription: (_o: any, _a: any, fallback: any) => fallback,
+  }),
+  useObjectTranslation: () => ({
+    t: (key: string, options?: any) => String(options?.defaultValue ?? key),
+    language: 'zh-CN',
+    i18n: undefined,
+  }),
+}));
+
+vi.mock('../useActionModal', () => ({
+  useActionModal: () => ({
+    modalHandler: vi.fn(async () => ({ success: true })),
+    modalElement: null,
+    closeModal: () => {},
+    resolveModalTarget: vi.fn(async () => null),
+  }),
+}));
+
+vi.mock('../../views/ActionConfirmDialog', () => ({ ActionConfirmDialog: () => null }));
+vi.mock('../../views/ActionParamDialog', () => ({ ActionParamDialog: () => null }));
+vi.mock('../../views/ActionResultDialog', () => ({ ActionResultDialog: () => null }));
+vi.mock('../../views/FlowRunner', () => ({ FlowRunner: () => null }));
+
+vi.mock('sonner', () => {
+  const fn: any = vi.fn();
+  fn.error = vi.fn();
+  fn.success = vi.fn();
+  return { toast: fn };
+});
+
+import { useConsoleActionRuntime } from '../useConsoleActionRuntime';
+
+// Every pack resident, so the `zh` line is the catalogue a Chinese console has.
+registerBuiltInLocales();
+
+const REFUSAL = 'You do not have permission to perform this action. Contact your administrator if you need access.';
+const NESTED = "Node 'recalc_each' failed: map 'recalc_each': item 0 (subflow 'showcase_recalc_task_estimate') failed: "
+  + `Node 'write_estimate' failed: update_record(showcase_task) failed: ${REFUSAL}`;
+
+const RECALC = {
+  name: 'showcase_recalc_estimate',
+  label: 'Recalculate Estimate',
+  type: 'api',
+  target: '/api/v1/apps/showcase/recalc',
+  recordIdParam: 'recordId',
+  params: { _rowRecord: { id: 'task-1' } },
+};
+
+function answer(status: number, body: unknown) {
+  authFetchSpy.mockImplementation(async () =>
+    new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } }),
+  );
+}
+
+async function runRecalc() {
+  const { result } = renderHook(() =>
+    useConsoleActionRuntime({ dataSource: {}, objects: [], objectName: 'showcase_task' }),
+  );
+  let out: any;
+  await act(async () => {
+    out = await result.current.apiHandler({ ...RECALC } as any);
+  });
+  return out;
+}
+
+beforeEach(() => {
+  authFetchSpy.mockReset();
+  vi.stubGlobal('fetch', vi.fn(async () => new Response('{}', { status: 200 })));
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe('objectstack#27487 — console runtime: a flow-backed api action reads the run refusal', () => {
+  it("a refused nested map → subflow write shows the record form's permission line, in the host's language", async () => {
+    answer(400, {
+      success: false,
+      error: {
+        code: 'FLOW_FAILED',
+        message: NESTED,
+        httpStatus: 400,
+        details: { innerRefusal: { code: 'PERMISSION_DENIED', message: REFUSAL } },
+      },
+    });
+
+    const out = await runRecalc();
+
+    expect(authFetchSpy).toHaveBeenCalledTimes(1);
+    expect(out).toEqual({ success: false, error: builtInLocales.zh.form.noPermissionToSave });
+  });
+
+  it('CONTROL: a 4xx that is not FLOW_FAILED reads its own message', async () => {
+    answer(403, { success: false, error: { code: 'PERMISSION_DENIED', message: 'Forbidden', httpStatus: 403 } });
+
+    expect(await runRecalc()).toEqual({ success: false, error: 'Forbidden' });
+  });
+});
@@ -52,6 +52,7 @@ import { EnvironmentEntitlementDialog, type EntitlementDialogState } from '../en
 import { entitlementDialogFromError, type EntitlementDialogSpec } from '../environment/entitlements.js';
 import { resolvePageVarTokens } from '../utils/resolvePageVarTokens.js';
 import { launchConsoleFlow } from '../utils/flowLaunch.js';
+import { apiActionFailureMessage } from '../utils/flowResponse.js';
 import { createConsoleServerActionHandler } from '../utils/consoleServerAction.js';
 import { withNewTabUrlFastPath } from '../utils/newTabUrlFastPath.js';
 import { modalTargetRefusalMessage } from '../utils/modalTargetDiagnostics.js';
@@ -510,7 +511,9 @@ export function useConsoleActionRuntime(opts: ConsoleActionRuntimeOptions): Cons
             openEntitlementDialog(entitlementSpec);
             return { success: false };
           }
-          return { success: false, error: errorDetail(body, `HTTP ${res.status}`) };
+          // A flow-backed endpoint's refused run reads its inner refusal, not
+          // the node chain (objectstack#27487).
+          return { success: false, error: apiActionFailureMessage(res, body, `HTTP ${res.status}`, language) };
         }
         const json = await res.json().catch(() => ({}));
         // A business rejection can arrive as HTTP 200 with `success: false`
@@ -630,7 +633,7 @@ export function useConsoleActionRuntime(opts: ConsoleActionRuntimeOptions): Cons
     } catch (error) {
       return { success: false, error: (error as Error).message };
     }
-  }, [dataSource, objApiName, objects, metadata, authFetch, activeOrganization, refresh, openEntitlementDialog, t]);
+  }, [dataSource, objApiName, objects, metadata, authFetch, activeOrganization, refresh, openEntitlementDialog, t, language]);
 
   /**
    * Flow action handler — starts the flow through one of two doors
 
@@ -12,7 +12,7 @@ import { ActionRunner } from '@object-ui/core';
 import { builtInLocales, registerBuiltInLocales } from '@object-ui/i18n/locales';
 import { ApiErrorSchema, FlowFailureDetailsSchema } from '@objectstack/spec/api';
 import type { AutomationResult } from '@objectstack/spec/contracts';
-import { flowSuccessCopy, interpretFlowResponse, judgeFlowLaunch } from '../flowResponse';
+import { apiActionFailureMessage, flowSuccessCopy, interpretFlowResponse, judgeFlowLaunch } from '../flowResponse';
 
 const ok = { ok: true, status: 200 };
 
@@ -743,3 +743,63 @@ describe('interpretFlowResponse — a refusal met inside the run, by the record-
         expect(on200(run({}))).toMatchObject({ error: RAW_ERROR });
     });
 });
+
+describe('apiActionFailureMessage — a flow-backed api action reads the run refusal, not the node chain (objectstack#27487)', () => {
+    registerBuiltInLocales();
+
+    // The card's toast: a map item's subflow met the refusal on its update.
+    const REFUSAL = 'You do not have permission to perform this action. Contact your administrator if you need access.';
+    const ONE_LEVEL = `Node 'write_estimate' failed: update_record(showcase_task) failed: ${REFUSAL}`;
+    const NESTED = "Node 'recalc_each' failed: map 'recalc_each': item 0 (subflow 'showcase_recalc_task_estimate') failed: "
+        + ONE_LEVEL;
+    const DENIED = { code: 'PERMISSION_DENIED', message: REFUSAL } as const;
+    const RULE = { code: 'VALIDATION_FAILED', message: 'Estimate must be a positive number.' } as const;
+
+    /** A declared `type: 'flow'` endpoint's `400 FLOW_FAILED`, proven real by the spec's own schemas. */
+    function endpointFailed(message: string, details: Record<string, unknown>, userMessage?: string) {
+        const error = {
+            code: 'FLOW_FAILED',
+            message,
+            httpStatus: 400,
+            ...(userMessage ? { userMessage } : {}),
+            details,
+        };
+        expect(ApiErrorSchema.safeParse(error).error?.issues).toBeUndefined();
+        expect(FlowFailureDetailsSchema.safeParse(details).error?.issues).toBeUndefined();
+        return { success: false, error };
+    }
+    const on400 = (json: unknown, locale?: string) => apiActionFailureMessage({ status: 400 }, json, 'HTTP 400', locale);
+
+    it("a one-level permission refusal reads the record form's line, in the host's language", () => {
+        expect(on400(endpointFailed(ONE_LEVEL, { innerRefusal: DENIED }))).toBe(builtInLocales.en.form.noPermissionToSave);
+        expect(on400(endpointFailed(ONE_LEVEL, { innerRefusal: DENIED }), 'zh-CN')).toBe(builtInLocales.zh.form.noPermissionToSave);
+    });
+
+    it('the nested map → subflow chain reads the same line once the inner refusal is carried', () => {
+        const shown = on400(endpointFailed(NESTED, { innerRefusal: DENIED }));
+        expect(shown).toBe(builtInLocales.en.form.noPermissionToSave);
+        expect(shown).not.toContain("Node '");
+        expect(shown).not.toContain('subflow');
+    });
+
+    it("a non-permission refusal reads its own sentence; a userMessage and the flow's errorMessage outrank it", () => {
+        expect(on400(endpointFailed(NESTED, { innerRefusal: RULE }))).toBe(RULE.message);
+        expect(on400(endpointFailed(NESTED, { innerRefusal: DENIED }, 'Ask your lead to recalculate.')))
+            .toBe('Ask your lead to recalculate.');
+        expect(on400(endpointFailed(NESTED, { errorMessage: 'Recalculation failed.', innerRefusal: DENIED })))
+            .toBe('Recalculation failed.');
+    });
+
+    it('an envelope without the members falls back to its message, never to silence', () => {
+        expect(on400(endpointFailed(NESTED, {}))).toBe(NESTED);
+    });
+
+    it('every other answer reads the envelope as the door always has', () => {
+        const denied = { success: false, error: { code: 'PERMISSION_DENIED', message: 'Forbidden', details: { innerRefusal: RULE } } };
+        expect(apiActionFailureMessage({ status: 403 }, denied, 'HTTP 403', 'en')).toBe('Forbidden');
+        // A 400 that is not FLOW_FAILED does not read flow carriers either.
+        const invalid = { success: false, error: { code: 'VALIDATION_FAILED', message: 'Bad body', details: { innerRefusal: RULE } } };
+        expect(apiActionFailureMessage({ status: 400 }, invalid, 'HTTP 400', 'en')).toBe('Bad body');
+        expect(apiActionFailureMessage({ status: 502 }, null, 'HTTP 502', 'en')).toBe('HTTP 502');
+    });
+});
@@ -125,6 +125,13 @@
  * `errorMessage` and `message`, and render the inner refusal by the record
  * form's rule. `message` itself is untouched on the wire.
  *
+ * The `type: 'api'` action door reads the same carriers (objectstack#27487).
+ * A declared `type: 'flow'` endpoint answers a run that failed with the
+ * trigger door's `400 FLOW_FAILED`, details included, and a flow-backed api
+ * action reached the user as that envelope's `message`, the node chain.
+ * {@link apiActionFailureMessage} is that door's reading: both api handlers
+ * (`useConsoleActionRuntime`'s and `RecordDetailView`'s) call it on a non-2xx.
+ *
  * ## A LAUNCH is judged here too, not just interpreted (objectui#9973)
  *
  * Classifying the response was never the whole rule. The two launch handlers
@@ -363,7 +370,9 @@ function permissionDeniedLine(locale: string | undefined): string {
  * `flows.FLOW.errorMessage` (objectui#12075) — then the producer-marked
  * `userMessage`, then the refusal the run's write node met (`innerRefusal`,
  * whose `message` the spec serves without the node and operation prefixes),
- * then the run's own `message`.
+ * then the run's own `message`. `locale` is the language the permission line
+ * is read in: the flow's own (`copy.locale`) on a launch or resume, the
+ * host's active language on the api action door, which knows no flow.
  *
  * The inner refusal is rendered exactly as the record form renders the same
  * refusal on a save: a permission denial (`isPermissionError`) becomes the
@@ -373,7 +382,12 @@ function permissionDeniedLine(locale: string | undefined): string {
  * permission check exactly as the form asks it (objectstack#26059, Q3). `message` stays the last rung, so a
  * run that met no refusal still says something, never nothing.
  */
-function flowFailureMessage(failure: FlowFailureCarriers, message: string, copy: FlowCopyLocale | undefined): string {
+function flowFailureMessage(
+    failure: FlowFailureCarriers,
+    message: string,
+    copy: FlowCopyLocale | undefined,
+    locale: string | undefined,
+): string {
     const friendly = failure.errorMessage;
     if (typeof friendly === 'string' && friendly.length > 0) return translatedFlowMessage('errorMessage', friendly, copy);
     if (failure.userMessage) return failure.userMessage;
@@ -382,7 +396,7 @@ function flowFailureMessage(failure: FlowFailureCarriers, message: string, copy:
         const refusal = { code: inner.code, message: typeof inner.message === 'string' ? inner.message : '' };
         const scopeReason = delegationScopeMessage(refusal);
         if (scopeReason) return scopeReason;
-        if (isPermissionError(refusal)) return permissionDeniedLine(copy?.locale);
+        if (isPermissionError(refusal)) return permissionDeniedLine(locale);
         if (refusal.message.trim()) return refusal.message;
     }
     return message;
@@ -411,6 +425,50 @@ function errorEnvelopeDetails(json: unknown): FlowRunResult {
     return details as FlowRunResult;
 }
 
+/**
+ * The message of a `400 FLOW_FAILED` error envelope, by
+ * {@link flowFailureMessage}: the carriers are `error.details`' `errorMessage`
+ * and `innerRefusal` and the envelope's top-level `userMessage`, and the last
+ * rung is the envelope's own message (`fallback` when it has none).
+ */
+function flowFailedEnvelopeMessage(
+    json: unknown,
+    fallback: string,
+    copy: FlowCopyLocale | undefined,
+    locale: string | undefined,
+): string {
+    const details = errorEnvelopeDetails(json);
+    return flowFailureMessage(
+        {
+            errorMessage: details.errorMessage,
+            userMessage: declaredUserMessage((json as { error?: unknown } | null | undefined)?.error),
+            innerRefusal: details.innerRefusal,
+        },
+        actionErrorDetail(json, fallback),
+        copy,
+        locale,
+    );
+}
+
+/**
+ * The error a `type: 'api'` action shows for a non-2xx answer (objectstack#27487
+ * — see the header). A `400 FLOW_FAILED` is a flow the endpoint ran, and reads
+ * the run's refusal by the failed arm's rule; `locale` is the host's active
+ * language, since the door knows no flow to translate an `errorMessage` for.
+ * Every other answer reads `actionErrorDetail`, as the door always has.
+ */
+export function apiActionFailureMessage(
+    res: { status: number },
+    json: unknown,
+    fallback: string,
+    locale: string | undefined,
+): string {
+    if (res.status === 400 && errorCodeIs((json as { error?: unknown } | null | undefined)?.error, 'FLOW_FAILED')) {
+        return flowFailedEnvelopeMessage(json, fallback, undefined, locale);
+    }
+    return actionErrorDetail(json, fallback);
+}
+
 /**
  * Classify a `POST /api/v1/automation/{flow}/trigger` or
  * `.../runs/{runId}/resume` response.
@@ -432,18 +490,9 @@ export function interpretFlowResponse<S = unknown>(
         // authorable `errorMessage` stays preferred for it; the envelope's own
         // `message` is the fallback. See the header note.
         if (res.status === 400 && errorCodeIs(json?.error, 'FLOW_FAILED')) {
-            const details = errorEnvelopeDetails(json);
             return {
                 kind: 'failed',
-                error: flowFailureMessage(
-                    {
-                        errorMessage: details.errorMessage,
-                        userMessage: declaredUserMessage(json?.error),
-                        innerRefusal: details.innerRefusal,
-                    },
-                    actionErrorDetail(json, `${label} failed`),
-                    copy,
-                ),
+                error: flowFailedEnvelopeMessage(json, `${label} failed`, copy, copy?.locale),
                 retryable: false,
             };
         }
@@ -492,6 +541,7 @@ export function interpretFlowResponse<S = unknown>(
                 },
                 actionErrorDetail(data, `${label} failed`),
                 copy,
+                copy?.locale,
             ),
             retryable: false,
         };