Codex 讓工作區限額錯誤說人話

Codex 把信用額度與 spend cap 失敗改成工作區專屬訊息，讓錯誤不再只會吐「失敗」兩個字。

我用 agentic coding 工具一陣子了，最煩的不是它寫錯 code，是它出事時像個不肯講人話的客服。明明只是某個 workspace 的額度爆了，它偏偏回我「something went wrong」。我先查 prompt，再查 auth，再查 network，最後才想到可能是錢包或 spend cap。這種鬼打牆我真的受夠了，因為它不是技術問題，是資訊設計爛掉。

這次我看到 OpenAI Codex changelog 裡一條很短的更新，才覺得這團東西終於有點像產品了。它只說了一件事：workspace-specific usage-limit messages now appear for credit and spend-cap failures。沒有大張旗鼓，沒有裝狠，但這種改法其實很實在，因為它直接把責任邊界講清楚了。

不要再把額度失敗包成一坨爛錯誤

Displayed workspace-specific usage-limit messages for credit and spend-cap failures.

翻譯一下就是：如果 Codex 因為某個 workspace 的 credit 用完，或 spend cap 到頂而停下來，它現在應該直接講是哪個 workspace、卡在哪個限制。不是「請重試」，不是「發生錯誤」，而是把真正的阻塞點丟出來。

我以前在內部 AI 工具也踩過這種坑。兩個 workspace 共用同一個產品介面，一個預付 credits 沒了，另一個還活著，結果錯誤訊息只寫「billing issue」。support 看到傻眼，工程師開始查 log，使用者以為整個系統掛了。其實只是其中一個 workspace 沒錢了，另一個完全正常。

這種錯誤最討厭的地方在於，它會把「可修復的行政問題」偽裝成「神秘的系統故障」。一旦訊息不指向正確邊界，大家就會開始亂猜。猜 prompt、猜模型、猜 API、猜網路，最後才輪到真正的原因。這不是效率問題，這是把人力拿去燒。

實操上，我會把每一種 billing failure 都拆成三件事：發生在哪個 workspace、是哪種 limit、下一步要做什麼。像這樣：

• Workspace 名稱要直接出現在訊息裡。
• limit type 要明確區分 credit 和 spend cap。
• 修復動作要能讓 admin 直接照做。

credit 跟 spend cap 不是同一件事，別再混著講

OpenAI 這次把 credit failure 跟 spend-cap failure 分開，我覺得這才像有在跑產品的人會做的事。兩個字看起來都跟錢有關，但操作語意完全不同。credit 比較像你卡裡的餘額，spend cap 比較像公司訂的花費上限。一個是錢沒了，一個是規則不准你再花。

白話一點講，這兩種錯誤對應的人根本不同。credit 用完，通常是財務或帳務的人去補；spend cap 到了，通常是 admin 或 workspace owner 去調政策。你如果把它們都叫「payment failed」，support 會被迫當偵探，還要自己猜是補值還是改設定。

我之前看過一個多租戶 admin panel，所有 quota 問題都吐「payment issue」。結果 ticket 來一堆，內容全錯。有人跑去問帳務，有人跑去問工程，有人甚至重開帳號。後來我們把錯誤拆成「balance exhausted」跟「policy cap reached」，整個 support queue 立刻乾淨很多。不是因為系統變強，是因為訊息終於不再裝死。

實操寫法很簡單：先定義兩個不同的 error code，再各自對應不同文案。不要偷懶把它們塞進同一個 enum。API 回傳要能讓前端、CLI、support 都讀得懂，否則你只是把問題從 UI 挪到 log。

• credit exhausted：表示可用餘額沒了。
• spend cap reached：表示政策上限到了。
• 兩者都要有不同的修復動作。

workspace-specific 這四個字，重點其實是 ownership

我覺得這條 changelog 真正有料的地方，不是 usage-limit，而是 workspace-specific。這四個字代表一件事：錯誤不是飄在空中的，它屬於某個邊界。它不是全域問題，不是所有人都要一起陪葬，而是某個 workspace 自己的狀態出了事。

這在多團隊環境超重要。你有 production workspace、staging workspace、測試 workspace、不同專案的 budget，訊息如果不帶邊界，所有人都會先懷疑自己。結果一個 workspace 爆掉，十個人一起查自己的設定，浪費時間到不行。

我在 CI 系統也看過同樣的爛戲。共享 org token 過期，錯誤訊息卻只寫「auth failed」。每個工程師都以為是自己 local 壞掉，最後才發現是同一個 org 的 token 失效。這種問題不是難修，是難找。找不到就會變成組織成本。

實操上，我會把 workspace id 從後端一路傳到前端，別只留在 telemetry。錯誤 response 要帶，UI 要顯示，support note 也要有。你如果真的希望人能修它，就不要把邊界藏起來。

另外，workspace-scoped errors 也很適合 app、CLI、API 三種場景一起用。App 可以友善一點，CLI 可以短一點，API 則要結構化。可是核心資訊不能變：是哪個 workspace、卡在哪個 limit、接下來該找誰。

這種小更新，才看得出產品有沒有長大

我很愛看這種 changelog 小條目，因為它通常比大字標語誠實。沒人會特地寫一條「改善錯誤訊息」的更新，除非前面真的有一堆人踩坑。也就是說，團隊已經看過 support 壓力、看過使用者困惑、看過工程師被迫查無聊問題，才決定把這個洞補起來。

這種改動不會讓 demo 更好看，但會讓工具更像真的能在公司裡活下來。因為公司環境不是只有模型準不準，還有 budgets、admins、permissions、billing rules。這些東西一旦錯了，訊息如果還在裝神秘，整個系統就會顯得很不成熟。

OpenAI 的 Codex 主頁、changelog，再加上周邊的 app、CLI、workspace 文件，已經很明顯是在往完整工作流走。工具一旦走到這一步，最值錢的往往不是模型分數，而是那些很無聊但很要命的邊角：權限、限額、連線、恢復、通知。

實操寫法就是一句：把重複出現的 support 問題，當成產品問題處理。只要同一個錯誤被問第三次，我就會要求它有更準的訊息。因為每多一個模糊錯誤，就等於多一個人去猜。

我會怎麼把這招搬進自己的工具

如果是我在做 coding agent 或內部平台，我不會只學它的文案，我會學它的結構。錯誤訊息要先講 workspace，再講 limit type，最後講 action。這三段缺一個，使用者就會開始翻頁、查 log、問同事，然後把原本五秒能解的事拖成半小時。

我也會把不同受眾拆開。前端畫面可以寫得像人話，API 要回結構化欄位，CLI 要短，support note 要完整。很多團隊最愛偷懶的地方，就是把同一段字到處貼。結果每個人都看不懂，然後怪使用者不會讀。

我還會補一個很現實的東西：信任。當工具願意老實說「你這個 workspace 的 spend cap 到了」，我反而比較願意相信它。至少它沒有拿一坨空話糊我臉。對我來說，這種坦白比漂亮 UI 有用多了。

實操上可以先做一個很小的 error taxonomy，先拆四類就夠了：balance、cap、permission、connectivity。每一類都要有一個對應的 user message、一個 API code、以及一個 support action。先把這四個做對，後面再慢慢補細節。

可抄的模板

## Workspace usage-limit error template（可直接貼進產品規格 / prompt / API 設計）

### 1) User-facing message
Workspace {{workspace_name}} has reached its {{limit_type}} limit.

### 2) Short explanation
{{limit_type}} is preventing Codex from continuing in this workspace.

### 3) Next step
{{resolution_action}}

### 4) Examples
- Workspace Acme has reached its credit limit. Add credits or wait for the balance to refresh.
- Workspace Acme has reached its spend cap. Increase the cap or ask an admin to review billing settings.

### 5) API error shape
{
  "error": {
    "code": "workspace_usage_limit",
    "workspace_id": "{{workspace_id}}",
    "workspace_name": "{{workspace_name}}",
    "limit_type": "credit|spend_cap",
    "message": "Workspace {{workspace_name}} has reached its {{limit_type}} limit.",
    "resolution_action": "{{resolution_action}}"
  }
}

### 6) CLI output
Error: Workspace {{workspace_name}} hit its {{limit_type}} limit.
Fix: {{resolution_action}}

### 7) Support note
Affected workspace: {{workspace_name}} ({{workspace_id}})
Failure type: {{limit_type}}
Recommended action: {{resolution_action}}

### 8) Implementation rule
- credit = balance problem
- spend cap = policy problem
- workspace must be explicit
- action must be actionable

原始來源是 OpenAI Developers Codex changelog，我前面拆的是這一條更新的產品意義。模板跟整理方式是我自己整理的，可直接拿去改成你們家的錯誤訊息規格。