# IGP Unity SDK 错误代码参考

本文档列出 Unity 适配层里最常见的错误来源和排查方式。

## 1. API 业务错误码

这些错误通常由后端或宿主桥返回，会通过 `IGPSDKException`、`Task` 异常或 `IGPRuntimeManager.onError` 暴露出来。

| 错误代码 | 含义 | 常见场景 | 建议操作 |
| --- | --- | --- | --- |
| `INVALID_INPUT` | 请求参数无效 | state key / RPC payload / team id 不合法 | 校验入参与 JSON 结构 |
| `ROOM_NOT_FOUND` | 房间不存在 | launch ticket 失效、房间已销毁 | 刷新房间上下文，确认由 desktop 正确拉起 |
| `PLAYER_NOT_FOUND` | 玩家不存在 | 当前玩家未出现在房间快照里 | 检查房间快照和会话 token |
| `ROOM_FULL` | 房间已满 | join 阶段 | 让玩家重试或切换房间 |
| `TOO_MANY_ROOMS` | 房间数达到上限 | 平台限流 | 降低重试频率，转交平台处理 |
| `UNAUTHORIZED` | 未授权 | session token 无效 | 重新获取 launch ticket |
| `FORBIDDEN` | 权限不足 | 非 host 调 start/finish/rematch | 在游戏层区分 host-only 行为 |
| `PLAYER_ALREADY_IN_ROOM` | 玩家已在房间中 | 重复 join / attach | 避免并发重入 |
| `PLAYER_NOT_IN_ROOM` | 玩家不在房间中 | leave / ready / team change | 先刷新 room snapshot |

## 2. Network 结果码

这些枚举由 `IGP.UnitySDK.Network.IGPNetworkResult` 返回，主要对应 data plane 读写。

| 枚举值 | 含义 |
| --- | --- |
| `kSuccess` | 操作成功 |
| `kErrorUnknown` | 未知网络错误 |
| `kErrorInvalidParam` | 参数无效，例如 payload 超过当前 KCP 直接发送或分片上限 |
| `kErrorInvalidState` | 当前状态不允许发包或读包 |
| `kErrorServiceNotAvailable` | 数据面当前不可用 |
| `kErrorNetworkUnReachable` | 网络不可达 |
| `kErrorNetworkRemotePeerOffline` | 目标玩家已离线 |
| `kErrorNetworkServerUnavailable` | 服务端不可用 |
| `kErrorNetworkConnectionDenied` | 连接被拒绝 |
| `kErrorNetworkConnectionClosed` | 连接已关闭 |
| `kErrorNetworkConnectionReset` | 连接被重置 |
| `kErrorNetworkError` | 通用网络错误 |

## 3. Hosted session / realtime 常见错误

| 现象 | 可能原因 | 处理方式 |
| --- | --- | --- |
| `Hosted session error` | desktop 控制通道未附着 | 确认是从 Curio desktop 房间页拉起游戏 |
| `Launch ticket bootstrap failed` | 启动参数缺失或 launch ticket 非法 | 检查宿主启动参数是否正确注入 |
| `Message type is reserved` | 调用了保留 control message type | 使用显式 hosted control API，而不是手发保留消息 |
| `Hosted data plane connection timeout` | 数据面未按预期握手成功 | 检查 server / desktop / UDP 可达性 |

## 4. KCP / 数据面错误

底层 `IGPKcpClient` 可能通过 `onError` 或日志暴露这些问题：

| 错误 | 含义 |
| --- | --- |
| `DnsResolve` | 无法解析服务器域名 |
| `Timeout` | 连接超时或心跳丢失 |
| `Congestion` | 网络拥塞，发送频率过高 |
| `InvalidReceive` | 收到非法数据包 |
| `InvalidSend` | 发送了非法数据 |
| `ConnectionClosed` | 连接被主动或被动关闭 |
| `Unexpected` | 非预期系统异常 |

## 5. 错误处理建议

### 监听统一入口

```csharp
runtimeManager.onError.AddListener(errorMessage =>
{
    Debug.LogError($"[IGP Runtime] {errorMessage}");
});
```

### 检查 data plane 返回值

当前 KCP 数据面统一按可靠处理。
`SendData(...)` 适合单条直接发送，`SendReliableData(...)` 适合需要自动分片的大消息。

```csharp
var result = runtimeManager.Network.SendData(runtimeManager.PlayerId, "", payload, (uint)payload.Length, 101);
if (result != IGP.UnitySDK.Network.IGPNetworkResult.kSuccess)
{
    Debug.LogWarning($"SendData failed: {result}");
}
```

### 先判状态再发起房间操作

```csharp
if (!runtimeManager.IsHostedSessionAttached || string.IsNullOrEmpty(runtimeManager.CurrentRoomId))
{
    Debug.LogWarning("Hosted room context is not ready.");
    return;
}
```

## 6. 优先级说明

当前 Unity 主线接入优先覆盖：

- room lifecycle
- realtime messaging
- achievements
- data plane / RTT

授权验证失败会通过 `onAuthorizationFailed` 和 `onError` 同时暴露。
如果游戏方没有自己接提示，SDK 还会显示一个默认保底提示层。
