连接和 API 问题

解读 Convai 会话错误代码、阅读 ConvaiRoomManager 诊断信息，并解决身份验证、传输和速率限制故障。

所有会话错误都会通过 ConvaiSessionEventRelay.OnSessionError。事件载荷包含一个 错误代码 字符串和一个人类可读的 消息。错误代码遵循分层点号格式： {category}.{detail}。类别前缀会告诉你系统的哪一层失败了。

类别前缀	发生故障的部分
config.*	SDK 配置——缺少 API 密钥或 Character ID
connection.*	Convai API 或网络——身份验证、路由、限制
transport.*	WebRTC / LiveKit 层——ICE、对等连接、信令
server.*	Convai 后端管道——配额、致命错误
session.*	会话生命周期——令牌过期、状态冲突

订阅会话错误

添加 ConvaiSessionEventRelay 到与……相同的 GameObject ConvaiManager 并在 Inspector 中连接，或在代码中订阅：

using Convai.Runtime.Presentation.Events;
using UnityEngine;

public class ErrorListener : MonoBehaviour
{
    [SerializeField] private ConvaiSessionEventRelay _sessionRelay;

    private void OnEnable()
    {
        _sessionRelay.OnSessionError.AddListener(OnError);
    }

    private void OnDisable()
    {
        _sessionRelay.OnSessionError.RemoveListener(OnError);
    }

    private void OnError(SessionErrorRelayData data)
    {
        Debug.LogError($"[MyApp] 会话错误: {data.ErrorCode} — {data.Message}");
    }
}

直接读取错误状态

ConvaiRoomManager 将最近的错误代码和消息作为普通属性存储——无需订阅事件。对于按需记录诊断状态，这很有用：

var room = FindFirstObjectByType<ConvaiRoomManager>();
Debug.Log($"状态:           {room.CurrentState}");
Debug.Log($"已连接:       {room.IsConnected}");
Debug.Log($"上一个错误代码: {room.LastSessionErrorCode}");
Debug.Log($"上一个错误消息:  {room.LastSessionErrorMessage}");
Debug.Log($"连接尝试次数:{room.ConnectAttemptCount}  重连次数: {room.ReconnectCount}");

配置错误

配置错误会在连接时立即触发——在任何网络流量之前。请先修复这些问题。

错误代码	说明	修复
config.api_key_missing	中的 API 密钥字段为空 ConvaiSettings	打开 Edit → Project Settings → Convai SDK 并粘贴你的 API 密钥
config.character_id_missing	CharacterId 上的字段 ConvaiCharacter 为空	在以下位置设置 Character ID： ConvaiCharacter Inspector 字段

如果 API 密钥为空，SDK 会在任何连接尝试之前发出警告： Convai 引导程序：未配置 API 密钥。请在 Edit > Project Settings > Convai SDK 中设置你的 API 密钥。 这会在播放时触发——请在测试连接前修复。

连接错误

当 Convai 拒绝或无法满足连接请求时，会出现这些代码。大多数都有明确原因和直接修复方法。

错误代码	说明	自动重试	修复
connection.connect_invalid_api_key	API 密钥被 Convai 拒绝	没有	从 Convai 仪表板复制一个新的密钥；检查末尾是否有空格
connection.auth_failed	身份验证失败（令牌已撤销或凭据错误）	没有	重新输入你的 API 密钥；检查该密钥是否已在仪表板中被撤销
connection.invalid_token	提供的连接令牌无效	没有	令牌由内部生成——如果出现此错误，请重新连接以生成新令牌
connection.connect_invalid_session_id	连接请求使用了无效的会话标识符	没有	会话 ID 由内部生成——请重新连接以重置会话
connection.connect_character_not_found	你的账户中不存在该 Character ID	没有	确认 Convai 仪表板中的 Character ID 完全一致
connection.connect_realtime_not_allowed	此账户未启用实时访问	没有	升级你的 Convai 套餐或联系支持
connection.connect_concurrency_limit_reached	你的套餐已达到同时会话上限	是	断开空闲的角色；升级套餐以获得更高上限
connection.connect_speaker_limit_reached	此账户已达到后端发言者上限	是	减少并发活动角色数量
connection.connect_bot_start_failed	Convai 管道启动失败（临时后端问题）	是	SDK 会自动重试；如果持续出现，请联系支持
connection.connect_unhandled_server_exception	连接过程中 Convai 发生未处理异常	是	SDK 会自动重试；如果持续出现，请查看 Convai 状态页面
connection.timeout	连接未能在超时时间内完成	是	检查互联网连接；增加 连接超时 在设置中（默认 30 秒，最大 120 秒）
connection.network_error	DNS 失败、套接字错误或网络不可达	是	验证互联网连接；检查 Convai 域名是否未被防火墙阻止
connection.rate_limited	在短时间内发出了过多连接请求	是	降低重连尝试频率；在代码中为重试之间添加延迟
connection.service_unavailable	Convai 暂时不可用（HTTP 503）	是	等待后重试；SDK 会自动退避
connection.server_error	Convai 返回了 5xx 错误	是	临时性问题——SDK 会重试；如果持续出现，请查看 Convai 状态页面
connection.not_found	未找到资源（角色或房间）（HTTP 404）	没有	确认你的账户中存在该 Character ID
connection.bad_request	连接请求中的参数无效	没有	检查 CharacterId 和其他连接参数是否不包含无效字符
connection.connect_validation_error	连接请求未通过 API 验证（HTTP 422）	没有	查看错误消息，了解哪个字段未通过验证
connection.failed	未被特定代码涵盖的通用连接失败	取决于	检查 LastSessionErrorMessage ，详见

传输错误

传输错误发生在 WebRTC / LiveKit 层，即 Convai 已接受连接请求之后。它们几乎总是临时性的，SDK 会自动重试。

错误代码	说明	检查内容
transport.ice_failed	WebRTC ICE 协商失败——无法到达对等端	确认网络允许 UDP 流量；企业防火墙常会阻止 WebRTC
transport.peer_connection_failed	无法建立 WebRTC 对等连接	与 ICE 失败相同——检查 UDP 端口和 STUN/TURN 可访问性
transport.livekit_error	LiveKit SDK 报告了错误	通常是临时性的；检查网络稳定性
transport.signal_disconnected	LiveKit 信令服务器连接已断开	通常会自动重连；持续失败表明网络不稳定

WebRTC 需要 UDP 端口可访问。在企业部署中，请与你的网络团队合作，将 Convai LiveKit 端点加入白名单。有关域名和端口的完整列表，请参见 Network & API Requirements 页面。

服务器和使用错误

错误代码	说明	修复
server.usage_limit_reached	已超过每日或每月使用配额	在 Convai 仪表板中查看使用情况；升级你的套餐
server.fatal_error	致命管道错误——会话已由 Convai 终止	会话无法恢复；请重新发起连接
server.error	Convai 报告的非致命管道错误	SDK 会重试；如果持续出现，请向 Convai 支持报告

会话和协议错误

错误代码	说明	修复
session.token_expired	会话令牌已过期	重新连接以获取新令牌
session.invalid_state	在无效状态下尝试了某个操作	检查你的连接/断开连接调用顺序
session.cancelled	会话已被你的代码取消	如果你调用 DisconnectAsync 手动
protocol.message_invalid	从 Convai 收到了无效的协议消息	通常表示 SDK/后端版本不匹配；请更新 SDK
protocol.parse_failed	SDK 无法解析来自 Convai 的消息	通常表示 SDK/后端版本不匹配；请更新 SDK

重试行为

SDK 对临时性错误使用指数退避策略。每次失败尝试后，它会先等待再重试：

尝试	此次尝试前的延迟
1（初始）	无——立即
2	1 秒
3	2 秒
4（最终）	4 秒

四次尝试后，SDK 会放弃并触发 OnSessionError 并带上最终错误代码。 非临时性错误——例如 API 密钥无效、未找到角色或不允许实时访问——不会重试。 SDK 会触发 OnSessionError 立即。

以下错误代码会触发自动重试：

• connection.timeout
• connection.network_error
• connection.server_error
• connection.service_unavailable
• connection.rate_limited
• connection.connect_concurrency_limit_reached
• connection.connect_bot_start_failed
• connection.connect_unhandled_server_exception
• transport.ice_failed
• transport.signal_disconnected
• server.error

运行时诊断

读取 ConvaiRoomManager 使用状态属性来缩小连接失败范围。属性会实时更新——无需订阅事件。有关完整属性参考、诊断快照 API 和代码示例，请参见 Debug Tools Reference。

调试工具参考

快速参考：常见故障模式

症状	可能原因	修复	验证
config.api_key_missing 每次连接时	从未输入 API 密钥	Edit → Project Settings → Convai SDK → 粘贴密钥	重新进入播放模式——错误不再触发
connection.connect_invalid_api_key	错误或已撤销的 API 密钥	从 Convai 仪表板复制一个新的密钥	会话到达 已连接 状态
connection.connect_character_not_found	Character ID 拼写错误或账户错误	在 Convai 仪表板中验证；检查复制粘贴产生的空白字符	会话到达 已连接 状态
connection.connect_realtime_not_allowed	账户未启用实时功能	升级套餐	会话到达 已连接 状态
connection.timeout 每次	防火墙阻止连接	将 Convai 域名加入白名单；尝试使用其他网络	会话在超时窗口内连接成功
transport.ice_failed 反复地	严格防火墙阻止 UDP	允许 UDP；向网络管理员请求 TURN 中继	会话连接成功；WebRTC 协商完成
server.usage_limit_reached	配额已超出	查看 Convai 仪表板的使用情况页面	在使用量重置或升级套餐后，会话连接成功
角色连接一次后再也不重连	ReconnectPolicy 已达到上限	SDK 在 3 次重连尝试后停止（默认 MaxReconnectAttempts）；调用 ConnectAsync 再次以重试	ConnectAsync 调用成功；角色连接
connection.rate_limited	短时间内连接次数过多	在应用逻辑中的连接调用之间添加最小延迟	connection.rate_limited 不再触发
CurrentState 卡在 错误	无法恢复的会话故障	调用 DisconnectAsync() 然后 ConnectAsync() 以重置	会话转换为 已连接

下一步

有关 SDK 日志系统、内置诊断工具和会话指标的完整参考，请参见 Debug Tools Reference。

调试工具参考