错误处理
错误响应为 {error:{code,message},requestId}。不要把密钥、Cookie 或完整凭证放进错误日志。
| 错误码 | 含义 | 建议处理 |
|---|---|---|
| INVALID_KEY / KEY_REQUIRED | 密钥无效或缺失 | 检查厂商后端配置 |
| TENANT_DISABLED / APP_DISABLED | 厂商或应用停用 | 联系平台 |
| CONTRACT_EXPIRED | 合同到期 | 联系平台续期 |
| INSUFFICIENT_BALANCE | 余额不足 | 联系厂商充值 |
| ORIGIN_FORBIDDEN | 来源未授权 | 检查精确域名、协议和端口 |
| TIER_FORBIDDEN | 档位未授权 | 使用合同允许的档位 |
| INSPECT_LINK_REQUIRED | 检视档只能传检视链接 | 改用 item.inspect；编辑功能另开通 editor |
| ITEM_READ_ONLY | 当前访问不能修改物品参数 | 使用新的检视链接 load 或独立编辑器 |
| INVALID_ITEM | 物品参数格式错误 | 检查 query 或 inspect |
| GRANT_EXPIRED | 未兑换凭证过期 | 提示用户重新进入 |
| GRANT_MISMATCH | 凭证与来源/访问编号不符 | 检查是否复用了旧凭证 |
| IDEMPOTENCY_CONFLICT | 同一编号使用了不同参数 | 修复厂商请求编号逻辑 |
| DAILY_LIMIT / CONCURRENCY_LIMIT | 达到额度 | 等待或联系平台调整额度 |
| VISIT_CLOSED / VISIT_EXPIRED | 会话关闭或被撤销，无定时到期 | 提示用户重新进入 |
| GRANT_FAILED | SDK 获取凭证失败 | 显示提示，允许重试当前访问 |
| EMBED_TIMEOUT | 查看器未完成握手 | 检查嵌入地址及网络 |
请求超时不能直接推断没有扣费。同次进入沿用相同编号重试，后端返回原结果。不要用无限创建新 openId 的方式自动重试。
模型未支持、WebGPU 不可用、GPU 设备丢失等由实际检视器返回渲染错误。请保留 visitId 与错误码，展示可理解的提示。