错误码全表

平台错误码全表（构建时生成）与 SDK 可见的声网错误号映射、错误信封与重试建议。

由公开错误码定义生成

版本 v1.1.0 · 更新于 2026-10-26 · 修订 1

如何处理错误

先按 HTTP 状态码分流：401/403 检查凭证、服务开通与封禁规则；404 确认资源；

409 先查询当前状态；415 补上 Content-Type；429 退避；5xx 退避并保留 X-Request-Id。

再按 code 分支：它是稳定机器码，可安全用于重试判断与告警分类。
SDK 侧按 sdkCode 分支，便于从声网迁移的代码复用既有判断。

错误信封

所有失败的 REST 调用返回同一信封，code 是稳定机器码（见下表），message 与 reason 为可读原因（同时满足声网 RTC REST 用 message、云端录制用 reason 的两种读取习惯），sdkCode 是面向客户端的数值错误号。

json

{
  "code": "recording_quota_exceeded",
  "message": "recording concurrency limit reached",
  "reason": "recording concurrency limit reached",
  "sdkCode": 22,
  "details": {
    "limit": 5,
    "active": 5
  }
}

响应头始终回显 X-Request-Id，与日志、回调、审计记录使用同一个 id；排障时优先提供它。

本页由公开错误码定义在构建时生成，共 42 个错误码，另有成功占位码 ok（HTTP 200）不计入错误表。

错误码全表

retryable 目前统一为 false：该字段是错误码定义中的建议位，尚未按错误码逐项标注。下表保留定义中的原值（列 `retryable`），实际重试策略请按 HTTP 语义（列“重试建议”）执行，见常见问题与限制。

code	HTTP	sdkCode	SDK 常量	分类	retryable	含义	重试建议
`invalid_channel_name`	400	-102	`ERR_INVALID_CHANNEL_NAME`	参数校验	false	invalid channel name	修正请求后重试
`invalid_parameter`	400	-2	`ERR_INVALID_ARGUMENT`	参数校验	false	invalid parameter	修正请求后重试
`RTC_TOKEN_INVALID_REQUEST`	400	-2	`ERR_INVALID_ARGUMENT`	参数校验	false	invalid RTC token request	修正请求后重试
`RTC_UID_MAPPING_INVALID_REQUEST`	400	-2	`ERR_INVALID_ARGUMENT`	参数校验	false	invalid RTC uid mapping request	修正请求后重试
`invalid_appid`	401	-101	`ERR_INVALID_APP_ID`	鉴权	false	invalid appid	检查凭证 / 更换 Token，不要原样重试
`invalid_credentials`	401	-110	`ERR_INVALID_TOKEN`	鉴权	false	invalid credentials	检查凭证 / 更换 Token，不要原样重试
`invalid_token`	401	-110	`ERR_INVALID_TOKEN`	鉴权	false	invalid token	检查凭证 / 更换 Token，不要原样重试
`missing_authorization`	401	-110	`ERR_INVALID_TOKEN`	鉴权	false	missing Authorization header	检查凭证 / 更换 Token，不要原样重试
`token_channel_mismatch`	401	-110	`ERR_INVALID_TOKEN`	鉴权	false	token does not match channel	检查凭证 / 更换 Token，不要原样重试
`token_expired`	401	-109	`ERR_TOKEN_EXPIRED`	鉴权	false	token expired	检查凭证 / 更换 Token，不要原样重试
`token_not_yet_valid`	401	-110	`ERR_INVALID_TOKEN`	鉴权	false	token not yet valid	检查凭证 / 更换 Token，不要原样重试
`token_privilege_expired`	401	-109	`ERR_TOKEN_EXPIRED`	鉴权	false	token privilege expired	检查凭证 / 更换 Token，不要原样重试
`token_uid_mismatch`	401	-110	`ERR_INVALID_TOKEN`	鉴权	false	token does not match uid	检查凭证 / 更换 Token，不要原样重试
`unauthorized`	401	-9	`ERR_NO_PERMISSION`	鉴权	false	authentication required	检查凭证 / 更换 Token，不要原样重试
`app_disabled`	403	-101	`ERR_INVALID_APP_ID`	鉴权	false	app is disabled	检查封禁规则、服务是否开通、密钥是否轮换
`banned`	403	-17	`ERR_JOIN_CHANNEL_REJECTED`	鉴权	false	user is banned by a kicking rule	检查封禁规则、服务是否开通、密钥是否轮换
`join_rejected`	403	-17	`ERR_JOIN_CHANNEL_REJECTED`	鉴权	false	join channel rejected	检查封禁规则、服务是否开通、密钥是否轮换
`RTC_TOKEN_DENIED`	403	-17	`ERR_JOIN_CHANNEL_REJECTED`	鉴权	false	RTC token denied	检查封禁规则、服务是否开通、密钥是否轮换
`service_not_enabled`	403	-1	`ERR_FAILED`	鉴权	false	service is not activated for this project	检查封禁规则、服务是否开通、密钥是否轮换
`channel_not_found`	404	-113	`ERR_NOT_IN_CHANNEL`	未找到	false	channel not found	确认资源存在（频道/任务/规则）
`collaborator_not_found`	404	-1	`ERR_FAILED`	未找到	false	collaborator not found	确认资源存在（频道/任务/规则）
`outbox_not_found`	404	-1	`ERR_FAILED`	未找到	false	outbox event not found	确认资源存在（频道/任务/规则）
`project_not_found`	404	-1	`ERR_FAILED`	未找到	false	project not found	确认资源存在（频道/任务/规则）
`recording_not_found`	404	-1	`ERR_FAILED`	未找到	false	recording task not found	确认资源存在（频道/任务/规则）
`streaming_not_found`	404	-1	`ERR_FAILED`	未找到	false	streaming task not found	确认资源存在（频道/任务/规则）
`user_not_found`	404	-113	`ERR_NOT_IN_CHANNEL`	未找到	false	user not in channel	确认资源存在（频道/任务/规则）
`webhook_not_found`	404	-1	`ERR_FAILED`	未找到	false	webhook endpoint not found	确认资源存在（频道/任务/规则）
`already_in_channel`	409	-19	`ERR_ALREADY_IN_USE`	状态冲突	false	participant already in channel	先查询当前状态再决定是否重试
`project_exists`	409	-1	`ERR_FAILED`	状态冲突	false	project already exists	先查询当前状态再决定是否重试
`recording_invalid_state`	409	-8	`ERR_INVALID_STATE`	状态冲突	false	recording task is not in a valid state for this operation	先查询当前状态再决定是否重试
`streaming_invalid_state`	409	-8	`ERR_INVALID_STATE`	状态冲突	false	streaming task is not in a valid state for this operation	先查询当前状态再决定是否重试
`unsupported_media_type`	415	-4	`ERR_NOT_SUPPORTED`	参数校验	false	unsupported media type	设置 Content-Type: application/json
`rate_limited`	429	-12	—	限流	true	too many requests	按指数退避重试（配额/限流）
`recording_quota_exceeded`	429	-22	—	配额	true	recording concurrency quota exceeded	按指数退避重试（配额/限流）
`streaming_quota_exceeded`	429	-22	—	配额	true	streaming concurrency quota exceeded	按指数退避重试（配额/限流）
`internal_error`	500	-1	`ERR_FAILED`	内部错误	true	internal server error	可退避重试；持续出现请带 X-Request-Id 反馈
`recording_upstream_error`	502	-1	`ERR_FAILED`	上游依赖	true	egress upstream error	上游（Egress/RTMP）异常，可退避重试
`streaming_upstream_error`	502	-1	`ERR_FAILED`	上游依赖	true	rtmp upstream error	上游（Egress/RTMP）异常，可退避重试
`no_server_resources`	503	-103	`ERR_NO_SERVER_RESOURCES`	上游依赖	true	no server resources	依赖不可用，可退避重试
`RTC_PROVIDER_DISABLED`	503	-1	`ERR_FAILED`	上游依赖	true	RTC provider is disabled by configuration	依赖不可用，可退避重试
`RTC_PROVIDER_UNAVAILABLE`	503	-111	`ERR_CONNECTION_INTERRUPTED`	上游依赖	true	RTC provider unavailable	依赖不可用，可退避重试
`upstream_unavailable`	503	-111	`ERR_CONNECTION_INTERRUPTED`	上游依赖	true	upstream service unavailable	依赖不可用，可退避重试

错误号在接口定义中存为正数，SDK facade 通过 SdkErrorCode 暴露同绝对值的负数常量（例如 invalid_appid → 101 → -101 ERR_INVALID_APP_ID）。两者语义一致、符号不同，跨层比对时按绝对值匹配。

SDK 可见的声网错误号

SDK facade（@nimeet/rtc-web 及同构端）把失败统一表示为 { code, sdkCode, message, retryable }，其中 sdkCode 使用下列负值，让从声网迁移的应用沿用既有的错误判断分支。REST 层不返回负值，用上表正数 sdkCode 对齐。

sdkCode	常量	含义	对应 REST 错误码
`-1`	`ERR_FAILED`	通用失败（未映射的兜底）	REST 无直接对应（连接层）
`-2`	`ERR_INVALID_ARGUMENT`	参数非法	REST 无直接对应（连接层）
`-3`	`ERR_NOT_READY`	SDK 尚未就绪	REST 无直接对应（连接层）
`-4`	`ERR_NOT_SUPPORTED`	当前端不支持该能力	REST 无直接对应（连接层）
`-5`	`ERR_REFUSED`	调用被拒绝	REST 无直接对应（连接层）
`-7`	`ERR_NOT_INITIALIZED`	未初始化	REST 无直接对应（连接层）
`-8`	`ERR_INVALID_STATE`	当前状态不允许该操作	REST 无直接对应（连接层）
`-9`	`ERR_NO_PERMISSION`	没有权限	REST 无直接对应（连接层）
`-10`	`ERR_TIMEDOUT`	超时	REST 无直接对应（连接层）
`-17`	`ERR_JOIN_CHANNEL_REJECTED`	加入频道被拒绝	REST 无直接对应（连接层）
`-18`	`ERR_LEAVE_CHANNEL_REJECTED`	离开频道被拒绝	REST 无直接对应（连接层）
`-19`	`ERR_ALREADY_IN_USE`	已在频道中 / 资源占用	REST 无直接对应（连接层）
`-101`	`ERR_INVALID_APP_ID`	App ID 无效	REST 无直接对应（连接层）
`-102`	`ERR_INVALID_CHANNEL_NAME`	频道名非法	REST 无直接对应（连接层）
`-103`	`ERR_NO_SERVER_RESOURCES`	服务端资源不足	REST 无直接对应（连接层）
`-109`	`ERR_TOKEN_EXPIRED`	Token 已过期	REST 无直接对应（连接层）
`-110`	`ERR_INVALID_TOKEN`	Token 无效	REST 无直接对应（连接层）
`-111`	`ERR_CONNECTION_INTERRUPTED`	连接中断（可自动重连）	REST 无直接对应（连接层）
`-112`	`ERR_CONNECTION_LOST`	连接丢失（需重新入会）	REST 无直接对应（连接层）
`-113`	`ERR_NOT_IN_CHANNEL`	不在频道中	REST 无直接对应（连接层）

facade 额外定义（不来自声网）：RTC_RECONNECTING、RTC_PUBLISH_DENIED、RTC_DEVICE_NOT_FOUND。断开原因 -111 走自动重连，-112 需要重新入会。

错误码全表

如何处理错误#

错误信封

错误码全表

SDK 可见的声网错误号

如何处理错误