支援流程

回報問題要附什麼

一定要有	說明
`x-request-id`	失敗回應的 header（或 body 的 `requestId`）。沒有它，平台查不到這次請求。
發生時間	含時區
操作	HTTP 方法與路徑，例如 `PUT /v1/persons/{personId}/extensions/{extensionId}`
client id	`tp_…`
狀態碼與 `error` 代碼	例如 `403 capability_not_granted`
契約版本	見本文件頁尾，或離線包的 `manifest.json`

有幫助但不必要：重現步驟、頻率（每次／間歇）、你這端的 trace id。

絕對不要附的東西

access token、refresh token、client secret、service account secret。附了就等於外洩，平台會要求立刻輪替。
真實客戶的個資。要舉例請改成合成資料。
你的內網位址、叢集設定或資料庫連線字串。

如果你不小心把憑證貼進 issue 或聊天訊息：先要求撤銷（停用帳號或推進 epoch），再輪替，然後才處理原本的問題。撤銷在下一個請求生效。

自助排查

按順序做，大部分問題在第三步之前就會清楚：

看 error 代碼，對照錯誤・限流・重試。error 是穩定的，message 不是。
分辨 403 還是 503。403 是「不准」，去修授權；503 是「現在判不了」，退避重試。
呼叫 GET /v1/me。它會告訴你這張 token 實際上是誰、屬於哪個租戶、實際生效的 scope 有哪些。很多「為什麼 403」的答案就在 scopes 裡——少了那一項能力。
確認能力的狀態。能力索引標了 availability；preview 表示契約可用但實作與開通未完成。
對 mock server 重跑一次（見範例與 mock）。如果 mock 過、正式環境不過，問題在授權或開通，不在你的程式。

回報之前

先確認不是這三件常見事：

token 是 ID token 而不是 access token（401 invalid_token）。
少了那一項能力，或租戶方案不含（403 capability_not_granted / plan_capability_excluded）。
寫入沒帶 If-Match，或帶了過期的（409）。