Reference: Error Codes (DOC-REF-ERR-001)

KNOW API 根據路由不同，使用三種不同的錯誤回應格式：

App 錯誤 — 除 OAuth token/revoke/userinfo 端點外的所有路由回傳。格式為 { "error": "<訊息>" }。
OAuth RFC 6749 錯誤 — 由 /api/oauth/token、/api/oauth/revoke、/api/oauth/authorize 回傳。格式為 { "error": "<代碼>", "error_description": "<說明文字>" }。error 欄位固定為機器可讀的代碼（invalid_client、invalid_grant 等），不是人類語句。
Zod 驗證錯誤 — 任何使用 zValidator 驗證請求本體或查詢參數的路由皆可能回傳。狀態碼固定為 400，回應本體為原始的 ZodError issues 陣列（不包在 { error } 中）。

回應格式 (DOC-REF-ERR-002)

App 錯誤 — 除 OAuth token/revoke/userinfo 以外的所有路由：

{
  "error": "Not a participant"
}

OAuth RFC 6749 錯誤 — /api/oauth/token、/api/oauth/revoke、/api/oauth/authorize：

{
  "error": "invalid_grant",
  "error_description": "Authorization code expired"
}

Zod 驗證錯誤 — 使用 zValidator 的路由，狀態碼 400：

{
  "issues": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["email"],
      "message": "Required"
    }
  ],
  "name": "ZodError"
}

請依照該端點的文件說明，修正請求本體或查詢參數，使其符合 schema。

狀態碼與錯誤一覽 (DOC-REF-ERR-003)

4xx 錯誤

| 狀態碼 | 格式 | 錯誤值 | 說明 | 建議處理方式 | |--------|------|--------|------|-------------| | 400 | Zod | issues[] 陣列 | 請求本體或查詢參數未通過 schema 驗證 | 依 issues 中列出的欄位修正後重試 | | 400 | App | "Missing email or code" / "Missing token or email" | OTP 或魔法連結驗證請求缺少必要欄位 | 補上兩個必要欄位 | | 400 | App | "Missing query" | 使用者搜尋缺少 q 參數 | 加入 q 查詢參數 | | 400 | App | "lat and lng required" / "lat out of range" / "lng out of range" | 位置座標缺失或超出範圍（緯度：−90–90，經度：−180–180） | 提供有效的座標值 | | 400 | App | "Invalid theme" / "Invalid level" | 列舉欄位的值不在允許範圍內 | 使用文件中列出的允許值 | | 400 | App | "Invalid JSON" / "bad body" | 請求本體無法解析為 JSON | 確認 Content-Type 正確，並傳送有效的 JSON | | 400 | App | "partner query param required" / "partnerHandle required" / "targetId required" | 缺少必要的查詢參數或本體欄位 | 補上缺少的欄位 | | 400 | App | "<訊息>" （個人資料更新） | 個人資料驗證失敗，例如 "Username must be 3-30 characters"、"Username already taken" | 依錯誤訊息修正欄位內容 | | 400 | OAuth | error: "invalid_request" | 缺少必要的 OAuth 欄位（grant_type、code、redirect_uri、refresh_token 或 token） | 在請求中補上缺少的欄位 | | 400 | OAuth | error: "invalid_client" | client_id 不存在，或 redirect_uri 未在應用程式中註冊 | 在開發者後台確認 OAuth 應用程式設定 | | 400 | OAuth | error: "invalid_grant" | 授權碼或 refresh token 問題 — 未知、已使用、已過期、client 不符，或 PKCE 驗證失敗 | 參閱 error_description 了解具體原因；若已過期請重新啟動授權流程 | | 400 | OAuth | error: "unsupported_grant_type" | grant_type 不是 authorization_code 或 refresh_token | 使用支援的 grant type | | 401 | App | "Invalid API token" | vbc_ API token 不存在或已撤銷 | 從開發者後台重新產生 API token | | 401 | App | "Invalid partner token" | vbcp_ partner token 不存在或已撤銷 | 重新產生 partner token | | 401 | App | "Invalid OAuth token" | vbco_ access token 已過期或撤銷 | 使用 refresh token 呼叫 /api/oauth/token 更新 | | 401 | App | "Invalid session" / "Session expired" / "Unauthorized" | Session token 缺失、無法識別或已過期 | 提示使用者重新登入 | | 401 | App | "Invalid or expired code" / "Invalid or expired token" | OTP 或魔法連結錯誤或超過有效期（15 分鐘 / 24 小時） | 重新請求驗證碼或連結 | | 401 | App | "missing signature" / "bad signature" | Soketi webhook HMAC 簽章缺失或錯誤 | 確認 SOKETI_APP_SECRET 與設定一致 | | 401 | OAuth | error: "invalid_client" （token 端點） | client secret 不符或缺少憑證 | 在開發者後台確認 client_secret | | 401 | OAuth | error: "invalid_token" | 傳至 /oauth/revoke 或 /oauth/userinfo 的 token 無效或已過期 | Token 已失效，無需進一步處理 | | 401 | OAuth | error: "login_required" | 非互動式流程中使用者尚未驗證 | 將使用者引導至授權頁面 | | 403 | App | "Internal access required" | 路由僅限內部存取，不對外開放 | 請勿從公開程式碼呼叫此路由 | | 403 | App | "Forbidden" | 嘗試訂閱非自己的私人 Pusher 頻道 | 只訂閱屬於已驗證使用者的頻道 | | 403 | App | "not_connected" | 目標使用者尚未連結（或已撤銷）此 partner app | 請使用者先完成 partner app 連結再傳送訊息 | | 404 | App | "Not found" / "Session not found" / "No keys found" | 請求的資源不存在或無存取權限 | 確認 ID 或帳號；檢查權限設定 | | 404 | App | "Partner app not found" / "partner_app_not_found" | 找不到符合 handle 或 ID 的 partner app | 確認 partner handle 或 app ID | | 404 | App | "Not a participant" / "Webhook not found" / "Connection not found" | 指定父資源下的子資源不存在 | 確認該資源對此呼叫者是否存在 | | 404 | OAuth | error: "not_found" | Partner app 尚未設定 OAuth 功能 | 在開發者後台為此 partner app 啟用 OAuth | | 409 | App | "OAuth already enabled for this app" / "Handle already taken" | 與現有資源衝突 | 使用不同的 handle，或不要重複建立 OAuth app | | 429 | App | "rate_limited" + retryAfter（秒） | 超過速率限制 | 等待 retryAfter 秒後重試 | | 429 | App | "Too many magic link requests. Try again later." | 魔法連結速率限制（每封信每小時 3 次） | 稍後再重新請求連結 |

5xx 錯誤

| 狀態碼 | 格式 | 錯誤值 | 說明 | 建議處理方式 | |--------|------|--------|------|-------------| | 500 | App | "Internal server error" | 未預期的伺服器錯誤 | 記錄請求細節並回報；請勿立即重試 | | 500 | App | "partner_app_missing_system_user" | Partner app 未設定系統使用者 | 聯絡平台支援 |

已知限制： 少數內部 service 錯誤（例如資料庫記錄損毀或缺失）目前會以 500 "Internal server error" 的形式回傳，而非更明確的 4xx 錯誤。這些將在未來版本中改善為適當的客戶端錯誤。