常見問題

先看返回的錯誤碼，再核對對應設定。回應里的 request_id 可以幫助你從伺服器日志中找到這次操作，不要把完整金鑰貼進日志或截圖。

啟用失敗，先檢查什么？

檢查伺服器位址能否訪問、產品 ID 是否正確、授權碼是否完整，以及授權是否屬于這個產品。如果伺服器還沒部署，客戶電腦不能用你的 127.0.0.1 位址連線，它表示客戶自己的電腦。

錯誤碼	先做什么
`LICENSE_INVALID`	檢查產品 ID、完整授權金鑰和所屬產品
`LICENSE_EXPIRED`	查看授權到期時間，需要繼續使用時由廠商續期
`LICENSE_REVOKED` `DEVICE_RELEASED`	授權已被撤銷或裝置已釋放；客戶端會清除舊快取
`DEVICE_LIMIT_REACHED`	授權的裝置名額已占滿；釋放舊裝置，或修改該授權的裝置上限
`API_QUOTA_EXCEEDED`	API 硬額度已用完；查看當前周期和方案限制
`API_BALANCE_INSUFFICIENT`	API 超額餘額不足；檢查對應環境和幣種的餘額
`MONTHLY_QUOTA_EXCEEDED`	裝置硬額度已達到；它與授權的裝置上限是兩項不同限制
`IDEMPOTENCY_CONFLICT`	同一 Key 被用于不同正文；新操作換新 Key，重試保留原正文
`IDEMPOTENCY_EXPIRED`	舊回應或裝置綁定已失效；檢查當前狀態后，為新的操作使用新 Key

斷網后還能用，是否沒有驗證？

允許離線時，SDK 仍會在本機檢查伺服器簽章、產品、裝置、功能和到期時間。它只是沒有聯系伺服器。簽章快取過期，或已聯網收到撤銷、釋放等明確拒絕后，就不能繼續使用。

為什么驗證簽章或裝置檢查不通過？

公鑰不匹配、使用了其他產品的快取、把快取複製到另一臺電腦，都可能導致失敗。核對 trusted_keys 的金鑰 ID 和公鑰是否來自當前產品，再檢查是否更換或重裝了系統。

SDK 報 clock rollback 時，檢查系統時間是否被調回。修正時間后，嘗試主動聯網刷新授權。

完整的錯誤回應

{
  "error": {
    "code": "LICENSE_REVOKED",
    "message": "License was revoked"
  },
  "request_id": "99999999-9999-4999-8999-999999999999"
}

欄位	含義與處理
`error.code` · string	穩定的錯誤標識，程式按它判斷如何處理，不依賴 message 的文字。
`error.message` · string	說明失敗原因的文字，適合診斷或轉換為面向客戶的提示。
`request_id` · UUID	伺服器為這次 HTTP 請求生成的編號，供查日志。它不是授權 ID，也不是 Idempotency-Key。

For 400 / 415 correct fields or Content-Type; for 401 check the management key; for 403 inspect the licensing error; for 409 check limits, session state or idempotency conflicts; for 429 wait according to Retry-After. Runtime retries retain their Idempotency-Key and body. Recover management writes using each operation’s idempotency rules; never blindly repeat ordinary issuance or renewal after a timeout.

請求返回的 JSON 怎么看？

成功返回 data 和 request_id；失敗返回 error.code, error.message 和 request_id。保留錯誤碼和 request_id 就能定位多數問題。

需要檢查電子郵件、支付或部署設定時，繼續看支援與排查中查看。