接口返回一个六位数字，先要知道它出自哪个模块，才知道去查哪一块的配置。错误码由模块基码加偏移构成，规律清楚，但有两处例外会让纯按数字查的做法失效：有两组模块共用了同一个基码，还有一条码没有按规律走。下面这个模块把这些例外一并处理：输入码值，直接给出它可能对应的每一种情况。
这些码是怎么编的
每个模块有一个基码，模块内的错误在基码上按顺序加偏移。基码从 500000 起，目前用到 512000，模块之间留了 1000 的间隔。
这样编码的好处是看到一个数字就能大致判断范围：五十万开头的一段属于团队与成员，五十万一千那一段属于知识库，往后依次是应用、用户、对话、分享链接、接口凭证、通用错误、插件等等。完整对照见下面那张表。
这些码不是写在文档里的，它们来自代码里的枚举定义，每个模块一个文件，共 14 个文件、122 条。所以升级之后新增的码会直接出现在枚举里，本页的对照表也是从那些枚举定义整理出来的，不是手工维护的清单。
条数的分布本身也能说明问题集中在哪里。团队与成员那一块占 45 条，是所有模块里最多的一块，接近总数的三分之一；技能与知识库各占十几条；对话、插件这些只有两三条。换个说法：定义得最细的地方是权限与成员关系，这也是实际部署里最容易出问题的一层 —— 多人协作、成员组、资源可见范围这些配置组合起来的分支最多。
交互模块：错误码定位
输入接口返回的错误码，或者输入记得的那部分英文名，模块会给出它属于哪个模块、对应哪个枚举与文案键、定义在哪个文件里；如果这个码值同时属于两个模块，两种可能会一起列出来。
| 码值 | 模块 | statusText | 枚举 | i18nKey | 来源 |
|---|---|---|---|---|---|
| 500000 | team | notUser | notUser | common:code_error.team_error.not_user | packages/global/common/error/code/team.ts |
| 500001 | team | unPermission | unPermission | common:error_un_permission | packages/global/common/error/code/team.ts |
| 500002 | team | accountCancellationPending | accountCancellationPending | common:code_error.team_error.account_cancellation_pending | packages/global/common/error/code/team.ts |
| 500003 | team | teamOverSize | teamOverSize | common:code_error.team_error.over_size | packages/global/common/error/code/team.ts |
| 500004 | team | unAuthTeam | unAuthTeam | common:code_error.team_error.un_auth | packages/global/common/error/code/team.ts |
| 500005 | team | aiPointsNotEnough | aiPointsNotEnough | common:code_error.team_error.ai_points_not_enough | packages/global/common/error/code/team.ts |
| 500006 | team | datasetSizeNotEnough | datasetSizeNotEnough | common:code_error.team_error.dataset_size_not_enough | packages/global/common/error/code/team.ts |
| 500007 | team | datasetAmountNotEnough | datasetAmountNotEnough | common:code_error.team_error.dataset_amount_not_enough | packages/global/common/error/code/team.ts |
| 500008 | team | appAmountNotEnough | appAmountNotEnough | common:code_error.team_error.app_amount_not_enough | packages/global/common/error/code/team.ts |
| 500009 | team | pluginAmountNotEnough | pluginAmountNotEnough | common:code_error.team_error.plugin_amount_not_enough | packages/global/common/error/code/team.ts |
| 500010 | team | appFolderAmountNotEnough | appFolderAmountNotEnough | common:code_error.team_error.app_folder_amount_not_enough | packages/global/common/error/code/team.ts |
| 500011 | team | websiteSyncNotEnough | websiteSyncNotEnough | common:code_error.team_error.website_sync_not_enough | packages/global/common/error/code/team.ts |
| 500012 | team | reRankNotEnough | reRankNotEnough | common:code_error.team_error.re_rank_not_enough | packages/global/common/error/code/team.ts |
| 500013 | team | ticketNotAvailable | ticketNotAvailable | common:code_error.team_error.ticket_not_available | packages/global/common/error/code/team.ts |
| 500014 | team | groupNameEmpty | groupNameEmpty | common:code_error.team_error.group_name_empty | packages/global/common/error/code/team.ts |
| 500015 | team | groupNotExist | groupNotExist | common:code_error.team_error.group_not_exist | packages/global/common/error/code/team.ts |
| 500016 | team | cannotDeleteDefaultGroup | cannotDeleteDefaultGroup | common:code_error.team_error.cannot_delete_default_group | packages/global/common/error/code/team.ts |
| 500017 | team | groupNameDuplicate | groupNameDuplicate | common:code_error.team_error.group_name_duplicate | packages/global/common/error/code/team.ts |
| 500018 | team | userNotActive | userNotActive | common:code_error.team_error.user_not_active | packages/global/common/error/code/team.ts |
| 500019 | team | orgMemberNotExist | orgMemberNotExist | common:code_error.team_error.org_member_not_exist | packages/global/common/error/code/team.ts |
| 500020 | team | orgMemberDuplicated | orgMemberDuplicated | common:code_error.team_error.org_member_duplicated | packages/global/common/error/code/team.ts |
| 500021 | team | orgNotExist | orgNotExist | common:code_error.team_error.org_not_exist | packages/global/common/error/code/team.ts |
| 500022 | team | orgParentNotExist | orgParentNotExist | common:code_error.team_error.org_parent_not_exist | packages/global/common/error/code/team.ts |
| 500023 | team | cannotMoveToSubPath | cannotMoveToSubPath | common:code_error.team_error.cannot_move_to_sub_path | packages/global/common/error/code/team.ts |
| 500024 | team | cannotModifyRootOrg | cannotModifyRootOrg | common:code_error.team_error.cannot_modify_root_org | packages/global/common/error/code/team.ts |
| 500025 | team | cannotDeleteNonEmptyOrg | cannotDeleteNonEmptyOrg | common:code_error.team_error.cannot_delete_non_empty_org | packages/global/common/error/code/team.ts |
| 500026 | team | invitationLinkInvalid | invitationLinkInvalid | common:code_error.team_error.invitation_link_invalid | packages/global/common/error/code/team.ts |
| 500027 | team | youHaveBeenInTheTeam | youHaveBeenInTheTeam | common:code_error.team_error.you_have_been_in_the_team | packages/global/common/error/code/team.ts |
| 500028 | team | tooManyInvitations | tooManyInvitations | common:code_error.team_error.too_many_invitations | packages/global/common/error/code/team.ts |
| 500029 | team | datasetFolderAmountNotEnough | datasetFolderAmountNotEnough | common:code_error.team_error.dataset_folder_amount_not_enough | packages/global/common/error/code/team.ts |
| 500030 | team | sandboxNotSupport | sandboxNotSupport | common:code_error.team_error.sandbox_not_support | packages/global/common/error/code/team.ts |
| 500031 | team | disabled | disabled | common:enterprise_auth.error.disabled | packages/global/common/error/code/team.ts |
| 500032 | team | serviceNotConfigured | serviceNotConfigured | common:enterprise_auth.error.service_not_configured | packages/global/common/error/code/team.ts |
| 500033 | team | noRemainingTimes | noRemainingTimes | common:enterprise_auth.error.no_remaining_times | packages/global/common/error/code/team.ts |
| 500034 | team | alreadyVerified | alreadyVerified | common:enterprise_auth.error.already_verified | packages/global/common/error/code/team.ts |
| 500035 | team | enterpriseOccupied | enterpriseOccupied | common:enterprise_auth.error.enterprise_occupied | packages/global/common/error/code/team.ts |
| 500036 | team | tooFrequent | tooFrequent | common:enterprise_auth.error.too_frequent | packages/global/common/error/code/team.ts |
| 500037 | team | serviceError | serviceError | common:enterprise_auth.error.service_error | packages/global/common/error/code/team.ts |
| 500038 | team | serviceTimeout | serviceTimeout | common:enterprise_auth.error.service_timeout | packages/global/common/error/code/team.ts |
| 500039 | team | infoFailed | infoFailed | common:enterprise_auth.error.info_failed | packages/global/common/error/code/team.ts |
| 500040 | team | taskNotFound | taskNotFound | common:enterprise_auth.error.task_not_found | packages/global/common/error/code/team.ts |
| 500041 | team | taskExpired | taskExpired | common:enterprise_auth.error.task_expired | packages/global/common/error/code/team.ts |
| 500042 | team | amountError | amountError | common:enterprise_auth.error.amount_error | packages/global/common/error/code/team.ts |
| 500043 | team | amountFailed | amountFailed | common:enterprise_auth.error.amount_failed | packages/global/common/error/code/team.ts |
| 500044 | team | processing | processing | common:enterprise_auth.error.processing | packages/global/common/error/code/team.ts |
| 501000 | dataset | sameApiCollection | sameApiCollection | common:core.dataset.error.sameApiCollection | packages/global/common/error/code/dataset.ts |
| 501001 | dataset | notSupportSync | notSupportSync | common:core.dataset.error.notSupportSync | packages/global/common/error/code/dataset.ts |
| 501002 | dataset | unExistDataset | unExist | common:core.dataset.error.unExistDataset | packages/global/common/error/code/dataset.ts |
| 501003 | dataset | unExistCollection | unExistCollection | common:error_collection_not_exist | packages/global/common/error/code/dataset.ts |
| 501004 | dataset | unAuthDataset | unAuthDataset | common:core.dataset.error.unAuthDataset | packages/global/common/error/code/dataset.ts |
命中 122 条，先显示前 50 条。
模块与基码对照
这张表是按模块的完整分布，可以直接对照使用。最后一列标「有」的模块，它的部分码值与另一个模块重叠。
| 模块 | 基码 | 错误码条数 | 码值重叠 |
|---|---|---|---|
| team | 500000 | 45 | |
| dataset | 501000 | 13 | |
| app | 502000 | 5 | |
| user | 503000 | 10 | |
| chat | 504000 | 2 | |
| outLink | 505000 | 4 | |
| openapi | 506000 | 3 | |
| common | 507000 | 8 | |
| plugin | 508000 | 2 | |
| skill | 509000 | 17 | 有 |
| system | 509000 | 5 | 有 |
| s3 | 510000 | 3 | 有 |
| sandbox | 510000 | 4 | 有 |
| coupon | 512000 | 1 |
8 个码值对应两种不同的错误
有两组模块共用了同一个基码：一组是 skill 与 system，都从 509000 起；另一组是 s3 与 sandbox，都从 510000 起。于是下面这些码值同时对应两个不同的错误，光看数字判断不出是哪一个，要看返回里的 statusText。
| 错误码 | 可能是 | 也可能是 | 怎么区分 |
|---|---|---|---|
| 509000 | skill.skillUnExist | system.communityVersionNumLimit | 看返回里的 statusText |
| 509001 | skill.unAuthSkill | system.commercialFeature | 看返回里的 statusText |
| 509002 | skill.canNotEditAdminPermission | system.licenseAppAmountLimit | 看返回里的 statusText |
| 509003 | skill.invalidSkillName | system.licenseDatasetAmountLimit | 看返回里的 statusText |
| 509004 | skill.invalidDescription | system.licenseUserAmountLimit | 看返回里的 statusText |
| 510000 | s3.InvalidUploadFileType | sandbox.agentSandboxPermissionDenied | 看返回里的 statusText |
| 510001 | s3.UploadFileTypeMismatch | sandbox.agentSandboxInitializing | 看返回里的 statusText |
| 510002 | s3.FileUploadDisabled | sandbox.runtimeUpgradeFailed | 看返回里的 statusText |
这一组里最容易误判的是 509 开头那几个。skill 那一侧是技能本身的问题，比如技能不存在、名称不合法；system 那一侧是版本与授权的限制，比如社区版数量限制、商业版功能、应用或知识库或用户数超出授权。两者的处置方向完全不同：前者改配置，后者要看版本与授权。
还有一条码不在规律里
分享链接失效这一条的码值是 501，而它所属模块的基码是 505000。也就是说它没有按基码加偏移的规律走，所以按数字区间去猜模块的做法，在这一条上会得到错误的答案。
这条码在实际排查中出现得不少 —— 分享链接过期或被删除时返回的就是它。看到一个三位数的码，基本可以直接判断是这一条。
返回里的三样东西各有什么用
一次报错的返回里通常同时带着三样东西：数字码、statusText、以及一个用于取提示文案的键。三样各有各的用处，不要只留其中一样。
数字码适合做告警与统计。它是整数，便于按区间聚合，比如把五十万开头的一整段划成团队与权限类问题做趋势。但它不适合做唯一标识，一是有重叠，二是升级时会平移。
statusText 适合做唯一标识与日志检索。它在所有模块里唯一，跨版本也基本保留，所以自建的日志系统按它建索引最稳。
文案键用于取用户能看到的那句提示。同一个错误在不同语言下显示不同文字，而键是同一个。需要自定义提示语的时候，改的是这个键对应的文案，不是去改错误码。这一层容易被忽略：直接在前端按数字码写死中文提示，换语言时就没有对应版本了。
有两个枚举名按码值查不到
team.teamMemberOverSize、user.unAuthRole 这两个名字出现在枚举定义里，但没有对应的码值，所以按数字查不到它们，只能按名字查到。在日志里看到这两个名字时，不用去找它对应几号码。
另外本页的模块名按定义文件所在的路径取，不按文件顶部的注释取。部分文件的注释与它实际所属的模块不一致，按注释整理会把码值归到错误的模块下，而这类错误在对照表上看不出来。所以如果拿本页的模块名与代码注释对不上，以路径为准。
拿到一个错误码之后按什么顺序排
第一步是拿 statusText，先别拿数字。数字可能有歧义，statusText 在所有模块里都是唯一的，接口返回里两者都有。
第二步是看模块，模块决定去查哪一块的配置。知识库那一段的错误多与向量模型、索引任务、文件解析有关；团队那一段多与成员、权限、成员组有关；system 那一段几乎都与版本或授权有关，改配置解决不了。
第三步是拿枚举名去代码或文档里搜。枚举名比数字稳定，版本升级时数字有可能因为插入新错误而变化，而枚举名一般会保留。这也是排查时优先记枚举名的原因。
如果这三步之后仍然定位不到，把接口原始返回完整保留下来再往上反馈，只报一个数字往往需要来回确认好几轮。
版本差异与失效说明
本页的 122 条码值来自 v4.16.2。升级之后模块内新增的错误会让后面的偏移发生变化，所以跨版本对照时以枚举名为准，不要以数字为准。两组共用基码的情况在这个版本里存在，如果后续版本调整了基码分配，本页的重叠清单需要重新整理。
继续阅读
本页参数与判定规则取自 FastGPT 开源仓库 v4.16.2，核验日 2026-09-09。