維運
錯誤處理與排查
用錯誤代碼、連線事件與本機身分狀態快速定位問題，同時避免在支援過程洩漏 License Key 或 Token。
先分辨是哪一層失敗
本機身分問題
例如 REGISTRATION_INVALID、TPM Key 不存在、Namespace 改變或 registration.json 損壞。
DNS、TLS 或連線問題
例如 getaddrinfo failed、憑證驗證失敗、Timeout 或公司 Proxy 阻擋。
公開授權 API 拒絕
例如輸入資料不完整、Challenge 過期、簽章 Proof 無效或 License 狀態不允許。
授權規則不符合
例如 License 過期、撤銷、Machine／User／Process 上限或缺少 Entitlement。
connection.log 應該怎麼看
Log 以事件描述流程，不應包含 License Key、Token 或私密金鑰。排查時先找最後一個成功事件，再確認下一個失敗事件的 endpoint、status code 與 error code。
client.ready
challenge.requested
http.response 200
gateway.signature_verified
tpm.proof_created
proof.submitted
validation.completed流量防護狀態不是 License 結論
Gateway 為了保護 CPU、記憶體、資料庫與上游授權 API，可能在 License 驗證以前先回覆流量防護狀態。這些回應代表「目前不能處理這次請求」，不是 License 已過期、撤銷或無效；不要刪除 registration.json、重建 TPM Key 或要求使用者重新輸入 License Key。
HTTP／Code代表意義Client 正確處理
429／IP_BURST_LIMIT、IP_RATE_LIMIT、REGISTRATION_BURST_LIMIT、*_RATE_LIMIT、IP_CONCURRENCY、IP_TEMPORARILY_BLOCKED單一來源、特定 API 類別、同時請求或累進封鎖暫時超過門檻讀取 GatewayError.retry_after_seconds，對可安全重試的驗證／讀取操作等待後再試；禁止無延遲 for 迴圈。
503／GLOBAL_BURST_LIMIT、GLOBAL_RATE_LIMIT、GLOBAL_CONCURRENCY、EMERGENCY_TRAFFIC_MODE、PROTECTION_CONFIG_UNAVAILABLEGateway 全站容量自我保護、設定暫時不可讀，或 Effective Mode 已進入 Emergency採 bounded exponential backoff 並依產品策略 fail closed；不要把 503 顯示成 License invalid，也不要立即重新啟用裝置。
403／IP_DENIED來源 IP 或 CIDR 被管理規則拒絕停止自動重試，保留錯誤時間、來源網路與 code，聯絡管理員檢查 Denylist／Trusted Proxy。
429 的安全等待範例
import time
from keygen_device_sdk import GatewayError
def validate_with_bounded_retry(client, attempts: int = 3):
for attempt in range(attempts):
try:
return client.validate_or_raise()
except GatewayError as exc:
if exc.status_code != 429 or attempt + 1 >= attempts:
raise
delay = min(60, max(1, exc.retry_after_seconds or (2 ** attempt)))
time.sleep(delay)
raise RuntimeError("unreachable")
retry_after_seconds 由 SDK 解析 HTTP Retry-After 與 Gateway JSON Detail。範例只示範可安全重驗的 validation；不要直接複製到會扣 Usage 或建立資源的操作。
常見狀況
症狀優先檢查建議處理
getaddrinfo failedGateway URL 與 DNS確認正式網域可解析、URL 不含 /device/v1。
Gateway signature invalidPublic Key / Key ID確認 Client 使用管理員提供的目前信任根。
HTTP 429GatewayError.code 與 retry_after_seconds等待指定秒數，限制重試次數；不要建立緊密重試迴圈。
HTTP 503GLOBAL_* 或 EMERGENCY_TRAFFIC_MODE退避並停止高價值功能；這不是 License 無效。
HTTP 403／IP_DENIED來源 IP、公司 NAT、Trusted Proxy 與 Denylist停止重試並聯絡管理員。
REGISTRATION_INVALIDNamespace、Product 與 registration.json先用 recover；必要時在確認後本機重置。
License invalid / revokedLicense 狀態與 Policy停止受保護功能並聯絡管理員，不要自行改本機資料規避。
TPM delete failedSDK 版本與 Key Name確認使用管理員提供的目前 SDK，並比對正確的 expected_key_name。
聯絡管理員前準備
- SDK 版本與 Python 版本
- 作業系統版本
- 錯誤代碼與簡短 Detail
- connection.log 最後 30 至 50 行的去敏感內容
- 可重現步驟與發生時間
- Product 名稱或內部案件編號，但不要寄送 License Key