所有错误都返回 JSON：{ "success": false, "error": { "code": "...", "message": "..." } }。请按 code 做分支，不要依赖 message 文案。
| Code | HTTP | 含义 | 建议处理 |
|---|---|---|---|
LICENSE_NOT_FOUND | 404 | 授权码不存在或已被删除 | 提示检查授权码，不要自动重试 |
LICENSE_EXPIRED | 403 | 授权已过期 | 展示续费；保留只读能力 |
LICENSE_SUSPENDED | 403 | 授权被暂停 | 提示联系管理员 |
LICENSE_REVOKED | 403 | 授权被吊销 | 停止解锁付费功能 |
ACTIVATION_LIMIT | 409 | 设备名额已满 | 引导门户解绑旧设备 |
DEVICE_HELD | 409 | 设备被锁定或正在迁移 | 稍后重试或联系支持 |
SEAT_PAUSED | 403 | 席位超限，该成员暂停 | 扩容或移除成员 |
FLOATING_LICENSE | 409 | 浮动授权需要先获取会话 | 调用 floating checkout |
RATE_LIMITED | 429 | 请求过于频繁 | 指数退避；不要并发轰炸 |
INVALID_IDEMPOTENCY_KEY | 400 | 幂等键格式无效或复用了不同请求 | 每次重试复用同一个键 |
UNAUTHORIZED | 401 | 门户/管理接口未登录 | 重新登录或刷新 token |
LICENSE_KEY_REQUIRED | 401 | 受保护的发布源缺少授权 | 附带 license_key 或 token |
重试策略
- 5xx、超时与 429 可重试；4xx 业务错误不要盲目重试。
- 激活重试带上同一个 Idempotency-Key，避免重复占位。
- 指数退避加抖动，首次 1 秒，上限 30 秒。
- 离线时先信任本地 token，恢复网络后再续验。