# Error Model

## 目标

定义 IGP SDK 在跨引擎层面的统一错误语义。

## 设计原则

1. 引擎 adapter 可以有自己的异常或错误类型。
2. 但 core contract 必须复用同一组错误码和语义。
3. 不把 Unity / C# 运行时异常文本直接当平台协议。

## 推荐错误结构

最小字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | `string` | 稳定错误码 |
| `message` | `string` | 人类可读说明 |
| `retryable` | `bool` | 是否建议重试 |
| `details` | `object?` | 调试补充信息 |

## 当前稳定错误码

平台业务错误：

- `INVALID_INPUT`
- `NOT_FOUND`
- `UNAUTHORIZED`
- `FORBIDDEN`
- `CONFLICT`
- `ROOM_NOT_FOUND`
- `PLAYER_NOT_FOUND`
- `ROOM_FULL`
- `TOO_MANY_ROOMS`
- `PLAYER_ALREADY_IN_ROOM`
- `PLAYER_NOT_IN_ROOM`
- `INTERNAL_ERROR`

SDK / bridge 常见错误语义：

- `SESSION_BRIDGE_ERROR`
- `HOSTED_SESSION_NOT_ATTACHED`
- `HOSTED_REALTIME_NOT_READY`
- `DATA_PLANE_TIMEOUT`
- `UNSUPPORTED_DATA_PLANE_MODE`
- `INVALID_PROTOBUF_PAYLOAD`
- `DESKTOP_SESSION_REQUIRED`
- `DESKTOP_USER_CONTEXT_REQUIRED`
- `ROOM_CONTEXT_REQUIRED`
- `APP_ID_REQUIRED`
- `APP_ID_MISMATCH`
- `EXECUTABLE_PATH_REQUIRED`
- `EXECUTABLE_PATH_NOT_ALLOWED`
- `DESKTOP_SESSION_CAPABILITY_MISSING`

## 错误来源分层

### Core Error

平台业务失败，例如：

- 房间不存在
- 权限不足
- 成就上报参数非法

### Bridge Error

本地桥失败，例如：

- desktop 控制通道未附着
- desktop session 缺少登录用户上下文
- desktop session 不支持当前能力
- protobuf 包格式非法
- hosted session 请求超时

### Adapter Error

引擎封装失败，例如：

- Unity 对象已销毁
- GameObject 缺少必须组件

## 重试建议

### 可重试

- 临时网络问题
- desktop / bridge 短时不可用
- data plane attach 超时后重新 attach

### 不建议自动重试

- `INVALID_INPUT`
- `FORBIDDEN`
- 业务幂等冲突

## 当前 Unity 映射

当前 Unity 侧主要通过：

- `IGPSDKException`
- `Task` 异常
- `IGPRuntimeManager.onError`

来暴露错误。后续其他引擎 adapter 可以采用不同错误承载方式，但应保留相同 code 语义。
