错误码
调用失败时，OpenAPI 返回 4xx 或 5xx 状态码和统一的错误结构。程序请根据 HTTP 状态码和 code 判断错误类型，需要进一步区分原因时再看 details。message 是给人看的中文说明，只用于展示和记录日志，内容可能调整，不要用它做判断。
错误响应的结构
json
{
"error": {
"code": "rate_limited",
"message": "群消息过于频繁，请稍后再试",
"details": { "reason": "group_send_rate" },
"request_id": "GNBHUXHA426Q3YLRLCJOWY7ISK"
}
}| 字段 | 类型 | 说明 |
|---|---|---|
error.code | String | 错误码，见错误码列表 |
error.message | String | 中文说明。同一个 code 在不同情况下的 message 可能不同，如 404 not_found 的“用户不存在”“接口不存在” |
error.details | Object | 附加信息，只有部分错误返回，没有时不返回这个字段。最常见的是 reason，说明具体原因，见 details 的取值 |
error.request_id | String | 这次请求的 ID，与响应头 X-Request-ID 相同，排查问题时请提供它 |
错误响应还可能带以下响应头：
| 响应头 | 说明 |
|---|---|
X-Request-ID | 每个响应都带，包括成功的响应。请求头中带了合法的 X-Request-ID 时原样返回，否则由服务端生成，见请求头 |
Retry-After | 429 时返回，需要等待的秒数，为整数，至少为 1 |
Allow | 405 时返回，这个路径支持的请求方法，如 POST |
批量接口中单项的失败不使用这个结构：整个请求返回 200 OK，失败的项各自带 code、message 和 details（有时才返回），取值与本页相同。例如批量添加群成员时：
json
{
"changed": false,
"member_version": 3,
"results": [
{ "username": "e-u4", "code": "permission_denied", "message": "该用户在群黑名单中", "details": { "reason": "group_blacklisted" } },
{ "username": "alice", "code": "limit_exceeded", "message": "群人数已达上限", "details": { "reason": "group_member_limit" } }
]
}错误码列表
以下是 OpenAPI 可能返回的全部错误码。各接口特有的情况见对应接口文档的“错误”一节。
| HTTP 状态码 | code | 含义 |
|---|---|---|
| 400 | invalid_argument | 参数缺失、格式不对或超出取值范围；请求体不是单个 JSON 对象、Content-Type 不是 application/json、含有接口不认识的字段或字段类型不对；分页游标无效。message 会指出是哪个参数，部分接口另在 details 中给出原因 |
| 401 | unauthenticated | 缺少 Authorization 请求头，或 App Token 无效、已过期、已失效。重新换取 App Token 后重试；details.reason 为 app_deleted 或 tenant_closed 时不要重试，见使用和缓存 App Token |
| 401 | invalid_client | 换取 App Token 时 Client ID 或 Client Secret 错误，或者 org_name、app_name 不存在（包括应用已删除、租户已注销） |
| 403 | permission_denied | App Token 不属于路径中的应用；或者业务规则不允许这项操作，如把群黑名单中的用户加入群，details.reason 说明原因 |
| 403 | ip_not_allowed | 来源 IP 不在应用的 IP 白名单内 |
| 403 | tenant_unavailable | 租户已暂停或处于注销冷静期，见应用和租户的状态 |
| 403 | app_unavailable | 应用已停用或被暂停服务；或应用处于只读状态，不能执行这项写操作 |
| 403 | user_disabled | 用户已被封禁，不能为他签发登录凭证；或者以被平台封禁的用户身份发送消息，此时 details.disabled_by 为 platform |
| 403 | not_group_member | 指定的用户不是该群的成员，如以非成员的身份发送群消息、设置非成员的群内角色；为用户设置群免打扰时，用户不是成员或群已解散 |
| 403 | group_disabled | 群已被封禁，不能执行这项操作（如添加成员），details.disabled_by 为 tenant（你封禁的）或 platform（平台封禁的） |
| 403 | chatroom_disabled | 聊天室已被封禁，不能执行这项操作（如发送消息），details.disabled_by 为 tenant（你封禁的）或 platform（平台封禁的） |
| 403 | message_rejected | 消息没有通过发送前的检查，没有发出或保存：被内容安全拒绝，或被你的同步回调拒绝。发送消息、编辑消息、批量发送消息（作为每个接收人的结果）和发送聊天室消息时都可能返回，details.reason 说明原因 |
| 403 | content_rejected | 资料或申请的内容（如昵称、群名称、好友申请的附言）没有通过内容安全检查，没有写入，details.field 指出字段，见内容安全 |
| 403 | file_blocked | 文件因违规已被屏蔽，不能下载，也不能由你删除。删除被屏蔽的文件时返回；换取下载地址时作为单项的结果返回，见下载与管理文件 |
| 404 | not_found | 资源不存在，如用户、群、会话、消息、聊天室不存在或已删除；聊天室已解散时 details.reason 为 chatroom_dismissed；message 为“接口不存在”时，是请求的路径写错了 |
| 405 | method_not_allowed | 路径存在，但不支持这个请求方法，响应头 Allow 列出支持的方法 |
| 409 | conflict | 资源或幂等状态冲突，详见独立 RTC 频道 |
| 503 | unavailable | 服务暂不可用，遵循 Retry-After 与操作重试规则，详见独立 RTC 频道 |
| 409 | already_exists | 要创建的资源已存在，如用户名已被占用 |
| 409 | version_conflict | 请求中的 version 与当前版本不一致，数据已被其他请求修改，见并发修改与 version；上传文件时表示上传当前的状态不允许这项操作，见文件接口 |
| 409 | limit_exceeded | 超出数量上限，如好友数、群人数、应用的存储额度，details.reason 说明是哪一项；应用的注册用户数已满时没有 details。注册用户数、群总数、存储容量等应用级的上限由应用的套餐决定 |
| 410 | file_expired | 文件已过期或已被删除。换取下载地址时作为单项的结果返回；删除约 30 天后，同一个文件地址改为返回 not_found |
| 413 | payload_too_large | 请求体超过 1 MiB；或者消息内容超过应用的消息大小上限、创建上传时文件的大小超过这种用途和类型的上限，此时 details.max_bytes 为上限的字节数 |
| 429 | rate_limited | 请求过于频繁，超出了调用额度或频率限制，按响应头 Retry-After 等待后重试，见限流与应用状态 |
| 500 | internal | 服务内部错误，具体原因不返回给调用方。可以稍后重试（带 Retry-After 时按它等待），持续出现时请带上 request_id 联系我们 |
details 的取值
details 中的字段因错误码而不同，下面列出 OpenAPI 可能返回的取值。以后可能增加新的取值，遇到不认识的取值时按 code 处理即可。
令牌与服务状态
code | details | 说明 |
|---|---|---|
unauthenticated | reason 为 app_deleted | 应用已被删除，App Token 永久失效，换取也会失败。请停止调用并清除保存的凭据 |
unauthenticated | reason 为 tenant_closed | 租户已注销，处理同上 |
tenant_unavailable | reason 为 arrears | 租户只因欠费被暂停服务，结清欠费后恢复，见逾期与欠费 |
app_unavailable | reason 为 arrears | 租户欠费，应用处于只读状态：可以查询，不能执行新增数据的写操作，结清欠费后恢复，见逾期与欠费 |
tenant_unavailable、app_unavailable 不带 details 时，是租户或应用被停用、暂停，或被平台设为只读，可以在控制台查看租户和应用的状态，见应用和租户的状态。
数量上限
limit_exceeded 的 details.reason，各项的数值见使用限制。其中应用的群总数、存储容量、聊天室数（以及没有 details 的注册用户数）由应用的套餐决定，群人数、用户加入的群数也不超过套餐的额度，见套餐的额度：
details.reason | 说明 |
|---|---|
friend_limit | 用户的好友数已达上限 |
peer_friend_limit | 对方的好友数已达上限 |
blacklist_limit | 用户的黑名单人数已达上限 |
group_member_limit | 群人数已达上限 |
user_group_limit | 用户加入的群数已达上限 |
app_group_limit | 应用中未解散的群数已达套餐的额度，不能再建群 |
admin_limit | 群或聊天室的管理员人数已达上限 |
group_blacklist_limit | 群黑名单人数已达上限 |
pinned_message_limit | 会话中置顶的消息数已达上限 |
edit_limit | 这条消息的编辑次数已达上限 |
storage_quota | 应用的存储用量加上这次上传的大小超过了存储额度（平台配额与套餐存储容量中较小的一个），另带 limit_bytes（额度）和 used_bytes（当前用量），单位为字节 |
group_file_limit | 群文件已满 1000 个 |
chatroom_limit | 应用中未解散的聊天室数已达上限（平台配额 chatroom_limit 与套餐的聊天室数中较小的一个），不能再创建聊天室 |
mute_limit | 聊天室的禁言名单已满 1 万个，在批量接口中作为单项的结果返回 |
ban_limit | 聊天室的封禁名单已满 1 万个，在批量接口中作为单项的结果返回 |
allowlist_limit | 聊天室的白名单已满 500 人，在批量接口中作为单项的结果返回 |
attribute_limit | 写入后聊天室属性的个数或合计大小超出上限，在设置属性的结果中作为没有写入的键的原因返回 |
conversation_setting_limit | 用户的会话免打扰已有 10000 个 |
word_list_limit | 应用的词库已有 20 个 |
word_limit | 添加后词库超过 10000 个词条，或应用合计超过 50000 个，这一批都没有添加 |
penalty_rule_limit | 自动处罚规则超过 5 条 |
频率限制
rate_limited 的 details.reason，等待的时间都在响应头 Retry-After 中：
details.reason | 说明 |
|---|---|
不带 details | 应用的 OpenAPI 调用额度已用完，或超出了其他频率限制（如换取 App Token、计算密码哈希） |
group_send_rate | 这个群每秒的消息数已达上限 |
app_message_rate | 应用每分钟的消息数已达配额 |
image_busy | 完成上传时图片处理繁忙，文件仍在上传中，稍后重新调用完成上传即可 |
room_send_rate | 这个聊天室或应用全部聊天室每秒的消息数已达上限。只对普通和高优先级的消息返回，低优先级的消息超出时被丢弃，不返回错误 |
room_attribute_rate | 这个聊天室每秒的属性写入已达 20 次 |
request_rate | 代用户举报超过每个应用每分钟 600 次 |
权限
permission_denied 的 details.reason：
details.reason | 说明 |
|---|---|
group_blacklisted | 用户在群黑名单中，不能加入这个群 |
not_editable | 只能编辑文本消息和自定义消息 |
message_recalled | 消息已被撤回或擦除，不能编辑或置顶 |
owner_protected | 不能禁言、移出或封禁聊天室的所有者，在批量接口中作为单项的结果返回。请先转让或清空所有者 |
target_banned | 要设为聊天室管理员的用户正在被这个聊天室封禁 |
not_revisable | 审核记录当前的状态不能作出结论、改判或转交，如把无违规改为违规、改判超过 30 天、记录已转交平台或已经结束，见作出结论 |
app_rejected | 客户端发送好友申请、加群时被你的加好友前、加群前回调拒绝，message 是你的服务端给出的提示，另带 app_reason，见同步回调 |
callback_unavailable | 加好友前、加群前回调失败（超时、接收端故障等），按失败策略拒绝了这项操作，另带 app_reason（为 null），见同步回调 |
解封或解散被平台封禁的聊天室时，返回不带 details 的 permission_denied，这样的聊天室只能由平台处理。
消息接口的参数错误
消息相关接口返回 invalid_argument 时，details.reason 说明具体原因：
details.reason | 说明 |
|---|---|
unknown_type | 不支持的消息类型 |
invalid_body | 消息内容不符合该类型的要求，details.field 指出字段 |
invalid_client_msg_id | client_msg_id 不是 1 到 64 个可见 ASCII 字符 |
reserved_client_msg_id | client_msg_id 以系统保留的 evt_ 或 sys_ 开头 |
invalid_recipient | to_user 和 to_group 没有恰好给出一个 |
from_required | 发送单聊消息或批量发送时没有给出 from |
self_conversation | 给自己发送消息 |
mentions_not_allowed | 在单聊中 @ 用户 |
invalid_reply | 引用的消息不存在、不可见或已撤回；或在批量发送中引用消息 |
receipt_not_allowed | 在单聊中，或以系统身份发送时要求已读回执 |
invalid_online_only | 只推在线的消息不是 custom 类型，或带了不允许的字段 |
invalid_push | push 不是 JSON 对象、含有 disabled、force、title、body、ext 以外的字段、取值不符合要求（如 disabled 和 force 同时为 true）或超过 2 KB，details.field 指出字段，见发送消息时的 push 字段 |
too_many_items | 一次提交的数量超过上限，details.field 为参数名，details.max 为上限 |
empty_edit | 编辑消息时 body 和 ext 都没有给出 |
conflicting_params | 拉取消息时 after_seq、before_seq、around_seq 给出了多个 |
文件接口
上传文件和下载与管理文件的接口返回 invalid_argument 时，details.reason 说明具体原因：
details.reason | 说明 |
|---|---|
invalid_purpose | 这个接口不能上传这种用途，或用途与类型 kind 不匹配 |
invalid_name | 文件名为空或不符合规则 |
unsupported_type | 完成上传时按文件内容识别出的格式不符合类型，details.content_type 为识别出的格式 |
size_mismatch | 上传的内容大小与创建上传时声明的不同。重新上传内容后再完成即可 |
upload_incomplete | 内容还没有上传，或分片不全、大小不对。上传完整后再完成即可 |
image_too_large | 图片超过 5000 万像素 |
invalid_image | 图片无法解码 |
upload_failed | 这次上传已经因格式不符、群文件已满等原因失败，重试完成也不会成功，需要重新创建上传 |
version_conflict 的 details.reason：
details.reason | 说明 |
|---|---|
upload_completed | 上传已经完成，不能再取消、索取分片的上传地址或查询已上传的分片。要删除已完成的文件请调用删除文件 |
upload_changed | 完成上传的过程中，内容又被重新上传了。重新调用完成上传即可 |
upload_completing | 另一个完成上传的请求正在处理这个文件，稍后重试 |
聊天室接口的参数错误
聊天室的接口返回 invalid_argument 时，details.reason 说明具体原因。发送聊天室消息时，消息内容的错误与消息接口相同（如 unknown_type、invalid_body）：
details.reason | 说明 |
|---|---|
invalid_priority | priority 不是 high、normal、low 之一 |
invalid_attribute_key | 属性的键不合法或重复，details.key 指出键 |
invalid_attribute_value | 属性的值不是字符串、超过 4096 字节或包含控制字符，details.key 指出键 |
attributes_too_large | 一次设置的键和值合计超过 16 KB，details.max_bytes 为上限 |
auto_delete_not_allowed | 服务端设置的属性不能标记 auto_delete |
推送接口的参数错误
推送设备与设置的接口返回 invalid_argument 时，details.reason 说明具体原因：
details.reason | 说明 |
|---|---|
invalid_duration | 免打扰的时长不在 1 到 315360000 秒（10 年）之间 |
invalid_quiet_hours | 夜间免打扰的时刻格式不对，或开始等于结束 |
invalid_timezone | 时区不是 IANA 时区名称 |
invalid_preview | 预览方式不是 full、sender_only、none |
invalid_mode | 会话免打扰的 mode 缺失或取值不对，或单聊设置了 mention_only |
self_conversation | 单聊免打扰的对方是用户本人 |
内容安全
内容没有通过内容安全检查时，消息类的接口返回 403 message_rejected，资料和申请类的接口返回 403 content_rejected，details 的取值：
details | 说明 |
|---|---|
reason 为 sensitive_content | 命中了拒绝的词库 |
reason 为 provider_block | 第三方审核判定违规；开启了头像审核时，头像的地址不能公开访问或是已被屏蔽的文件 |
reason 为 check_timeout | 第三方审核超时或出错，应用设置为超时时拒绝。不计入用户的违规，可以稍后重试。只出现在单聊、群聊消息和资料、申请的检查中，聊天室消息的第三方审核超时时一律放行 |
field | 只在 content_rejected 中返回，为被拒绝的字段，多个字段被拒绝时为其中的第一个：用户资料为 nickname、avatar_url；群资料为 name、description、announcement、avatar_url；群昵称为 group_nickname；入群申请为 message、reason；好友申请为 message、add_source；聊天室资料为 name、description、announcement |
批量发送消息时，被拒绝的消息在每个接收人的结果中都返回 message_rejected；批量创建用户时，被拒绝的用户出现在 failed 中，code 为 content_rejected，没有 details。这两个错误重试同样的内容不会成功，请提示用户修改内容。
审核配置与词库和审核记录与违规的接口返回 invalid_argument 时，details.reason 的取值：
details.reason | 说明 |
|---|---|
unsupported_scene | 场景不支持这种审核方式，如在消息和聊天室消息以外的场景使用发出后的第三方文本审核 |
provider_account_required | 开启了第三方审核，但应用还没有在控制台选择审核账号 |
unsupported_action | 屏蔽词库没有给出处理方式 action，或放行词库给出了 action |
invalid_action | 结论中的处置不适用于这个对象，如对用户资料撤回消息；或者无违规的结论带了处置 |
self_report | 代用户举报时，举报人举报自己或自己的消息 |
invalid_evidence | 代用户举报时证据消息不符合要求：举报的不是用户或群却附了证据消息；证据消息不存在、举报人看不到、已撤回，不是被举报的用户发的，或不在被举报的群里 |
同步回调
操作被你的同步回调拒绝时，发消息前、发聊天室消息前回调返回 403 message_rejected，加好友前、加群前回调返回 403 permission_denied，details 相同：
details | 说明 |
|---|---|
reason 为 app_rejected | 你的服务端拒绝了这项操作，message 是你给出的提示（没有给出时为“消息发送失败”或“操作被拒绝”） |
reason 为 callback_unavailable | 同步回调失败（超时、连接失败、响应无效等），按你设置的失败策略“拒绝”处理，见失败时的处理 |
app_reason | 你在响应中给出的原因代码，没有给出时以及 callback_unavailable 时为 null |
同步回调默认只对用户在客户端的操作调用。你的服务端发送消息（包括聊天室消息）、编辑消息时，只有对应的同步回调在调用条件 vias 中包含了服务端的操作才会调用；服务端添加好友、加人不调用加好友前、加群前回调。批量发送消息时只调用一次，被拒绝时每个接收人的结果都是 message_rejected。
其他字段
code | details | 说明 |
|---|---|---|
not_group_member | reason 为 leave_pending | 以用户的身份读取或操作群会话时，该用户刚离开群，相关处理还没完成。通常几秒后即可读到他离开前的消息，可以稍后重试 |
internal | reason 为 dependency_unavailable | 依赖的服务暂时不可用，按响应头 Retry-After 等待后重试：查询在线状态时（5 到 30 秒）；查询聊天室成员、移出聊天室成员、发送和撤回聊天室消息、查询最近的聊天室消息时（1 到 5 秒）。发送聊天室消息时消息没有发出，用同一个 client_msg_id 重试即可 |
user_disabled | disabled_by 为 platform | 用户被平台封禁，服务端不能以他的身份发送消息（包括聊天室消息）；被你封禁的用户仍然可以 |
group_disabled | disabled_by 为 tenant 或 platform | 群被谁封禁：tenant 为你（通过 OpenAPI 或控制台）封禁，platform 为平台封禁 |
chatroom_disabled | disabled_by 为 tenant 或 platform | 聊天室被谁封禁，含义同上 |
not_found | reason 为 chatroom_dismissed | 聊天室已解散。解散后 30 天内仍可以查询聊天室信息，其他接口返回这个错误，据此可以区分“已解散”和“不存在” |
payload_too_large | max_bytes | 应用的消息大小上限，或这种用途的文件大小上限，单位为字节 |
invalid_argument | field | 出错的字段，如消息内容中的字段、在线状态查询的 usernames |
invalid_argument | reason 为 invalid_date_range | 查询通话统计时缺少 from 或 to、格式不是 YYYY-MM-DD、to 早于 from，或超过 92 天 |
控制台和客户端接口的错误码
以下错误码不会由 OpenAPI 返回，只出现在控制台和客户端接口（用户以 User Token 调用的接口）中，列在这里供参考：
| HTTP 状态码 | code | 含义 |
|---|---|---|
| 400 | invalid_code | 验证码、两步验证动态码或恢复码错误或已失效 |
| 401 | invalid_credentials | 账号或密码错误，或用户的登录凭证无效、已使用、已过期 |
| 401 | mfa_required | 控制台登录时还需要输入两步验证动态码 |
| 401 | session_revoked | 用户的登录会话已被吊销，如在其他设备登录被挤下线、被踢下线、修改了密码，details.reason 给出原因，见下线原因 |
| 403 | reauth_required | 控制台的敏感操作（如添加推送凭据、新建回调地址）需要先重新验证身份 |
| 403 | captcha_required | 需要先完成图形验证 |
| 403 | mfa_setup_required | 租户要求全员开启两步验证，当前账号尚未开启 |
| 403 | invitation_target_mismatch | 当前账号与邀请的邮箱或手机号不一致 |
| 403 | user_muted | 用户被全局禁言，不能发送 |
| 403 | user_blocked | 因黑名单不能执行这项操作。发送好友申请时 details.by 为 self（你拉黑了对方）或 peer（对方拉黑了你）；发送单聊消息时只会是 peer |
| 403 | friend_add_denied | 对方设置了拒绝任何人添加好友 |
| 403 | not_friend | 应用开启了只能给好友发消息或只允许邀请好友入群，双方不是好友 |
| 403 | group_muted | 在群里被禁言，或群开启了全员禁言 |
| 403 | not_chatroom_member | 用户的这条连接不在聊天室中，如没有进入聊天室就发送聊天室消息、设置属性 |
| 403 | chatroom_muted | 在聊天室中被禁言（details.reason 为 member，details.muted_until 为到期时间，永久为 null），或聊天室开启了全员禁言（details.reason 为 all） |
| 409 | owner_transfer_required | 需要先转让所有者或群主身份，如退出租户、群主退群 |
| 409 | slot_unavailable | 两个 Secret 槽位都已占用，须先吊销一个；轮换回调的签名密钥时，旧密钥的宽限期还没有结束，见轮换密钥 |
| 409 | last_active_secret | 不能吊销应用最后一个有效的 Secret |
| 409 | device_limit_exceeded | 登录设备数已达上限，且应用设置为拒绝新设备登录 |
| 409 | call_in_progress | 本人已在通话中，不能再发起、接听或加入：details.reason 为 in_other_call（在另一个通话中，details.call_id 为那个通话）或 joined_on_other_device（已在本人的另一台设备上接听或加入了这个通话） |
| 409 | call_ended | 通话已经结束，不能再接听、加入、邀请、续期或心跳，details.end_reason、details.ended_at 为结束的原因和时间 |
| 410 | invitation_expired | 邀请已过期、已撤销或已被接受 |
| 429 | too_many_attempts | 登录失败次数过多，暂时限制登录 |
客户端和控制台接口中，常见的错误码还可能带以下 details.reason，它们不会由 OpenAPI 返回：
code | details.reason | 说明 |
|---|---|---|
limit_exceeded | app_connection_limit | 建立长连接时，应用的在线连接数已达套餐的并发连接数额度，新的连接被关闭；已经建立的连接不受影响。断开说明中带 30 到 60 秒的等待时间，客户端按它等待后再重新连接 |
limit_exceeded | chatroom_member_limit | 聊天室人数已满，不能进入 |
limit_exceeded | connection_room_limit | 这条长连接已经在 10 个聊天室中，不能再进入 |
limit_exceeded | call_full、call_member_limit | 群通话人数已满；群通话累计涉及的成员已达 100 人 |
limit_exceeded | app_concurrent_calls | 应用进行中的通话数已达套餐的并发通话额度，details.limit 为额度，见并发通话额度 |
limit_exceeded | credential_limit、template_limit | 控制台：应用的推送凭据已有 20 份；通知模板的覆盖已有 300 条 |
limit_exceeded | endpoint_limit、rps_limit | 控制台：应用已有 5 个回调地址；回调地址的每秒请求数超过了应用的上限，details.max 为上限 |
permission_denied | chatroom_banned | 用户被这个聊天室封禁，不能进入，details.expires_at 为到期时间，永久为 null |
permission_denied | priority_denied | 只有聊天室的所有者和管理员可以发送高优先级的消息 |
permission_denied | role_required | 需要聊天室的所有者或管理员身份，details.required_role 为需要的身份 |
permission_denied | admin_protected | 聊天室的管理员不能处置其他管理员 |
permission_denied | set_by_higher_role | 禁言或封禁是所有者或服务端设置的，管理员不能修改或解除 |
permission_denied | client_create_disabled | 应用没有允许客户端创建聊天室 |
permission_denied | recall_window_expired、recall_denied | 聊天室消息已超过撤回时限；没有撤回这条聊天室消息的权限 |
permission_denied | attribute_owned | 聊天室属性由别人设置，普通用户不能修改或删除，在设置、删除属性的结果中按键返回 |
permission_denied | rtc_disabled | 应用没有开启音视频：运行策略 rtc_enabled 没有开启，或应用的套餐不包含音视频 |
permission_denied | rtc_suspended | 本应用的音视频已被平台停用，details.suspend_reason 为原因 |
permission_denied | rtc_not_configured | 音视频服务暂不可用 |
permission_denied | not_host、not_in_call、not_joined_device | 不是发起人、群主或群管理员却结束群通话；不在通话中却邀请他人；不是在通话中的那台设备却续期媒体凭据 |
permission_denied | media_provider_unsupported | 客户端不支持当前的媒体服务，请提示用户升级 App |
permission_denied | report_disabled | 应用关闭了客户端举报（运行策略 report_enabled），代用户举报不受影响 |
permission_denied | platform_disabled | 控制台：推送凭据或回调地址已被平台停用，只有平台可以恢复 |
version_conflict | member_state | 本人在通话中的状态不允许这个操作，如接听之后又拒绝，details.member_state 为本人当前的成员状态（从未被邀请为 null） |
invalid_argument | invalid_ext | 进入聊天室或发起通话时的 ext 不符合要求 |
invalid_argument | invalid_target、self_call 等 | 通话操作的参数错误，见客户端需要做什么 |
invalid_argument | unknown_credential、platform_mismatch 等 | 客户端登记推送失败，见客户端登记推送令牌 |
invalid_argument | url_not_allowed | 客户端提交的头像、聊天室封面或附件地址不符合运行策略 media_url_only 的限制；控制台：回调地址的 URL 不符合要求，details.rule 指出原因，见地址的要求 |
invalid_argument | unknown_event_type、invalid_filter、invalid_condition | 控制台：回调地址订阅了不认识的事件类型（details.event_type 为这一项）；过滤条件不正确；同步回调的调用条件不正确 |
invalid_argument | endpoint_unverified、endpoint_disabled、endpoint_mismatch | 控制台：回调地址还没有通过 URL 验证；地址已被自动停用，请先恢复；同步回调绑定的不是本应用的回调地址。见回调配置 |
客户端接口还有按用户的频率限制，超出时返回 429 rate_limited，details.reason 为 request_rate（每分钟或每天的次数）、pair_daily_limit（同一个人每天向同一个人发送好友申请、向同一个群申请入群的次数）、declined_cooldown（被拒绝后 24 小时内不能再次申请或邀请）、group_join_rate（这个群每分钟入群的人数已满），发送消息时的 user_send_rate、new_conversation_rate、mention_rate、conversation_send_rate、peer_receive_rate，聊天室的 join_rate（每条连接每分钟进入的次数）、room_join_rate（这个聊天室每秒进入的人数已满）、attribute_rate（每个用户每分钟设置属性的次数），以及通话操作的 call_rate、pair_call_rate、group_call_rate、invite_rate、signal_rate、token_rate、query_rate（见音视频通话）。控制台中测试推送过于频繁时为 test_rate；回调地址的 URL 验证和测试发送超过每个应用每分钟 20 次时不带 details。
服务端代用户操作时不受其中大部分限制，例如以用户的身份发送消息时不检查禁言、黑名单和好友关系，见发送消息。
错误处理建议
按错误的类型决定是否重试：
| 错误 | 是否重试 | 建议 |
|---|---|---|
429 rate_limited | 是 | 按响应头 Retry-After 的秒数等待后重试，不要立即重试。持续出现时降低调用频率，见限流与应用状态 |
500 internal、网络错误、超时 | 是 | 用指数退避重试，如依次等待 1 秒、2 秒、4 秒，并加上随机的抖动，重试几次仍失败后告警。写操作的重试见下文 |
401 unauthenticated | 换取后重试一次 | 重新换取 App Token 后重试一次；仍然失败，或 details.reason 为 app_deleted、tenant_closed 时停止 |
409 version_conflict | 读取后再决定 | 重新读取最新的数据，确认仍需修改后带上新的 version 再提交 |
410 file_expired、403 file_blocked | 否 | 文件已过期、已删除或被屏蔽，重试也不会成功。客户端提示用户“文件已过期”或“文件已被屏蔽” |
403 tenant_unavailable、403 app_unavailable | 否 | 服务处于暂停或只读状态，短时间内重试没有意义。请告警，并在控制台查看租户和应用的状态；只读状态下查询仍然可用。details.reason 为 arrears 时请结清欠费，见逾期与欠费 |
403 message_rejected、403 content_rejected，以及 details.reason 为 app_rejected 的 403 permission_denied | 否 | 内容没有通过内容安全检查，或被你的同步回调拒绝，重试同样的内容也不会成功，请提示用户修改。details.reason 为 check_timeout（第三方审核超时）或 callback_unavailable（同步回调失败）时可以稍后重试 |
409 limit_exceeded | 否 | 已达数量上限，重试也不会成功。注册用户数、群总数、存储容量、聊天室数等应用级的额度用满时，请删除不再需要的数据或更换套餐，见套餐的额度 |
其他 4xx | 否 | 请求本身有问题（参数、权限或数据的状态），修正后再提交 |
写操作的重试要注意幂等。网络超时后，你无法确定上一次请求是否已经执行。查询可以直接重试；写操作请按重试与幂等的规则处理：
- 发送消息时带上自己生成的
client_msg_id，超时后用同一个值重试，不会重复发送； - 创建返回
409 already_exists、删除返回404 not_found时，可以视为上次已经成功； - 其他写操作先查询结果，再决定是否重试。
记录 request_id。请在日志中记下每个失败请求的 request_id，以及请求的时间、方法、路径和错误码，联系技术支持时提供它，可以快速找到这次请求。也可以在请求头 X-Request-ID 中传入你自己的追踪 ID，服务端会原样使用，便于把你的日志与我们的排查对应起来：
bash
curl "$IM_API/$ORG/$APP/users/zhangsan" \
-H "Authorization: Bearer $APP_TOKEN" \
-H "X-Request-ID: order-svc-7f3a9c"独立 RTC 频道
新增公共 code：409 conflict 表示资源 / 幂等状态冲突，503 unavailable 表示暂不可用；不替代 already_exists 或 version_conflict。具体原因如下：
| code | details.reason | 调用方处理 |
|---|---|---|
| invalid_argument | invalid_channel_id / invalid_request / invalid_role | 修正参数 |
| not_found | channel_not_found / session_not_found | 不存在或没有可见 / 会话权限；无效票据统一隐藏 |
| permission_denied | channel_banned / rtc_disabled / rtc_suspended | 修正授权或开通状态，不自动再加入 |
| conflict | channel_closed / session_left / join_deadline_exceeded | 停止本次会话并清理 |
| conflict | media_resource_busy / joined_on_other_device / session_already_exists | 查询当前会话，退出旧资源或恢复原会话 |
| conflict | idempotency_conflict | 同加入 / 管理操作键换了参数，不能重用 |
| already_exists | channel_id_used | 更换频道 ID，关闭的 ID 不可复用 |
| version_conflict | version_conflict / members_changed | 重读版本；成员列表从第一页刷新 |
| limit_exceeded | channel_full / active_media_limit / channel_limit | 等待清理或调整容量 / 额度 |
| unavailable | media_preparing / media_reclaiming / media_unavailable / admission_unavailable | 遵循 Retry-After，有界重试且保持原加入键 |
| unavailable | deployment_config_changed | 服务端实例配置需同步，请平台处理，不能换加入键绕过 |
加入准备中 503 可带本人 session_id / join_deadline；它不延长首次期限。票据签发不自动重试。媒体 Token 过期或 HTTP 授权拒绝后不能只凭 LiveKit 仍连接继续参与。SDK 本地无媒体能力为 unsupported，采集限制和权限错误见各端频道指南。