连接与 API 问题
解读 Convai 会话错误代码、查看房间管理器诊断信息,并解决身份验证、传输和限流失败。
所有会话错误都会通过 ConvaiSessionEventRelay.OnSessionError。事件载荷包含一个 ErrorCode 字符串以及一个人类可读的 Message。错误代码采用分层点号格式: {category}.{detail}。类别前缀告诉你系统的哪一层失败了。
config.*
SDK 配置——缺少 API key、Character ID 或 Auth Token 模式设置
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 将最近的错误代码和消息存储为普通属性——无需订阅事件。这对于按需记录诊断状态很有用:
配置错误
配置错误会在连接时立即触发——在任何网络流量之前。先修复这些问题。
config.api_key_missing
API key 字段为空,位于 ConvaiSettings
打开 Edit → Project Settings → Convai SDK 并粘贴你的 API key
config.character_id_missing
CharacterId 上的字段 ConvaiCharacter 为空
在……中设置 Character ID ConvaiCharacter Inspector 字段
config.auth_token_provider_missing
Auth Mode 是 Auth Token,但没有 IConvaiAuthTokenProvider 已注册提供程序,也未配置 Token Endpoint URL
注册一个提供程序或配置 Token Endpoint URL——参见 排查身份验证问题
config.auth_token_endpoint_invalid
已配置的 Token Endpoint URL 不是 HTTPS,也不是回环开发地址
使用 https://,或 http://localhost / http://127.0.0.1 用于本地开发——参见 排查身份验证问题
config.auth_token_mode_required
ConnectWithAuthTokenAsync 在 Auth Mode 仍为 API Key 时调用了
在调用前先在 Convai Project Settings 中将 Auth Mode 设置为 Auth Token ConnectWithAuthTokenAsync ——见 排查身份验证问题
连接错误
当 Convai 拒绝或无法满足连接请求时会出现这些代码。大多数都有明确原因和直接修复方法。
connection.connect_invalid_api_key
该 API key 被 Convai 拒绝
没有
从 Convai 仪表板复制一个新 key;检查是否有尾随空格
connection.auth_token_fetch_failed
Auth Token 模式在连接前未能解析出令牌(提供程序异常、令牌为空或端点失败)
是
参见 排查身份验证问题 查看确切的控制台消息和原因
connection.auth_failed
身份验证失败(令牌已撤销或凭据错误)
没有
重新输入你的 API key;检查该 key 是否已在仪表板中撤销
connection.invalid_token
提供的连接令牌无效
没有
令牌由内部生成——如果出现此项,请重新连接以生成新令牌
connection.connect_invalid_session_id
连接请求使用了无效的会话标识符
没有
Session 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
该账户已达到后端 speaker 上限
没有
减少同时处于活动状态的角色数量,或提高你的账户上限。SDK 不会对此重试——与并发限制不同,它被视为硬性限制,而不是临时状况。
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 信令服务器连接已断开
通常会自动重连;持续失败表明网络不稳定
服务器与使用错误
server.usage_limit_reached
已超过每日或每月使用配额
在 Convai 仪表板中查看使用情况;升级你的方案
server.fatal_error
致命管线错误——会话已被 Convai 终止
会话无法恢复;发起新的连接
server.error
Convai 报告了非致命管线错误
SDK 会重试;如果持续存在,请向 Convai 支持报告
会话与协议错误
session.token_expired
会话令牌已过期
重新连接以获取新令牌
session.invalid_state
在无效状态下尝试了某个操作
检查你的 connect/disconnect 调用顺序
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 key、找不到角色或不允许实时——完全不会重试。 SDK 会触发 OnSessionError 立即。
以下错误代码会触发自动重试:
connection.timeoutconnection.network_errorconnection.server_errorconnection.service_unavailableconnection.rate_limitedconnection.connect_concurrency_limit_reachedconnection.connect_bot_start_failedconnection.connect_unhandled_server_exceptionconnection.auth_token_fetch_failedtransport.ice_failedtransport.signal_disconnectedserver.error
运行时诊断
读取 ConvaiRoomManager 使用状态属性来缩小连接失败范围。属性会实时更新——无需订阅事件。完整属性参考、诊断快照 API 和代码示例请参见 Debug Tools Reference。
快速参考:常见故障模式
config.api_key_missing 每次连接时
从未输入 API key
Edit → Project Settings → Convai SDK → 粘贴 key
重新进入 Play 模式——错误不再触发
connection.connect_invalid_api_key
错误或已撤销的 API key
从 Convai 仪表板复制一个新 key
会话到达 已连接 state
connection.connect_character_not_found
Character ID 拼写错误或账户错误
在 Convai 仪表板中验证;检查复制粘贴产生的空白字符
会话到达 已连接 state
connection.connect_realtime_not_allowed
账户未启用实时功能
升级方案
会话到达 已连接 state
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 卡在 Error
无法恢复的会话失败
调用 DisconnectAsync() 然后 ConnectAsync() 以重置
会话转变为 已连接
下一步
关于 SDK 日志系统、内置诊断工具和会话指标的完整参考,请参见 Debug Tools Reference。
最后更新于
这有帮助吗?