TcaplusDB错误码
TcaplusDB 错误码
| 错误码 | 描述 | 详细说明 | 是否常见 | 解决方案 |
|---|---|---|---|---|
| 2309 | TXHDB_ERR_RECORD_IS_NOT_SET_TTL | 记录未设置过期时间 | N | 单条记录淘汰相关的，没有设置过期时间，让项目组检查SetTTL |
| 261 | TXHDB_ERR_RECORD_NOT_EXIST | 该记录不存在 | Y | 记录不存在，业务需要检查是否符合预期 |
| -256 | GEN_ERR_ERR | 通用错误码，一般PB sdk出现，需要具体查看sdk错误日志。 | 通常发生在RegistTable调用时，请检查: 1、RegistTable对应的参数的表是否已添加成功并通过审批(常见的表不存在或已申请但未完成审核) 2、dir若配置的域名， 请检查域名可正确解析 3、请检查telnet(curl) dir_ip dir_port可以成功， 即网络链路是没问题的(以往发生的比较多的情况是跨IDC、DEV访问网络不通) | |
| -261 | TXHDB_ERR_INVALID_ARGUMENTS | c内部参数错误 | N | db服务端内部错误，可联系tcaplus_helper排查 |
| -273 | PROXY_ERR_INVALID_PARAMS | DB服务端内部参数错误 | N | db服务端内部错误，可联系tcaplus_helper排查 |
| -275 | API_ERR_OVER_MAX_KEY_FIELD_NUM | 超过最大key个数限制，当前最大8个key，list表7个，业务若API版本比较旧，建议升级到3.46.0最新版本 | Y | 1、key数量超过，页面加表会拦截2、一般在setkey接口出现该错误，请排查setkey调用的次数，key个数是否超过限制 |
| -279 | DIR_ERR_SIGN_FAIL | dir认证失败 | N | 1.密码错误，请检查业务密码是否正确 2.检查dir地址是否正确 |
| -517 | TXHDB_ERR_INVALID_MEMBER_VARIABLE_VALUE | 内部参数错误 | N | |
| -525 | SVR_ERR_FAIL_TIMEOUT | 1、如果是api初始化失败，返回该错误，那么表示连接tcapdir或者连接tcaproxy超时，请检查：（1）dir若配置的域名， 请检查域名可正确解析（2）请检查telnet(curl) dir_ip dir_port可以成功， 即网络链路是没问题的(以往发生的比较多的情况是跨IDC、DEV访问网络不通)（3）如果是proxy连接超时，可以联系DBA或Tcaplus_Helper排查2、如果是响应包返回-525错误，一般是批量请响应包返回的，此时可以先看看是否持续报错：（1）如果只是偶尔出现，那么可能是网络波动导致的（2）如果持续出现，可以联系DBA或Tcaplus_Helper排查 | Y | 1、gamesevrer连接tcaproxy超时，需要看下：（1） Tcaplus API和tcaproxy版本是否满足Tcaplus API版本号<=tcaproxy版本号<=tcapsvr版本号；（2）tcaproxy的TCP连接数目限制；2、如果tcaproxy返回-525的错误响应包，一般是批量请求才会出现，原因通常是因为tcapsvr没有在超时时间内返回响应包，此时：（1）找到返回-525错误的tcaproxy，一般会有错误日志的；（2）找到返回记录超时的tcapsvr，确认一下tcapsvr的性能方面是否有问题； |
| -529 | PROXY_ERR_NO_NEED_ROUTE_BATCHGET_ACTION_MSG_WHEN_NODE_IS_IN_SYNC_STATUS | 有损搬迁中部分命令不支持， 目前大多为无损搬迁，不会有该错误码 | N | 有损搬迁时，对xxxbypartkey、delete相关的命令字不支持，返回错误码 |
| -531 | API_ERR_OVER_MAX_VALUE_FIELD_NUM | value字段数量超限，generic表限制数为128, List表限制数：1273.46.0版本增大到generic表限制数为256, List表限制数：255 | Y | 请根据版本排查数量是否超限，超过限制可下载最新版本升级 |
| -773 | TXHDB_ERR_ALREADY_OPEN | 引擎文件重复打开 | N | |
| -781 | SVR_ERR_FAIL_SHORT_BUFF | buf太短，内部错误 | N | |
| -785 | PROXY_ERR_NO_NEED_ROUTE_WHEN_NODE_IS_IN_REJECT_STATUS | 有损搬迁中部分命令不支持， 目前大多为无损搬迁，不会有该错误码 | N | 排查是否在有损搬迁，过程中部分命令操作不支持 |
| -787 | API_ERR_OVER_MAX_FIELD_NAME_LEN | 字段名称大小超过限制（32B） | Y | 字段名称超过限制，一般在页面加表会拦截，改小字段名称长度 |
| -1037 | SVR_ERR_FAIL_SYSTEM_BUSY | 存储层过载， 可联系DBA或Tcaplus_Helper排查， 常见原因：1、业务访问量较大， 存储层常规过载2、存储层磁盘性能异常，导致过载3、进程卡顿， 有ago日志 | Y | 1、确认tcapsvr性能是否有问题，比如磁盘性能，cpu等；2、如果性能没有问题，确认主线程是否有卡顿，搜索ago日志即可；3、搜索工作线程日志，是否有slow关键词的日志，slow日志表示处理某个请求耗时达到200ms以上； |
| -1043 | API_ERR_OVER_MAX_FIELD_VALUE_LEN | 1 字段值长度指超过表定义中的限制, 如定义string100B，实际写入101B时返回该错误2 单key字段内容超过1024 | Y | 1、根据表定义排查字段buf是否超限2、更新了表，本地的表meta是否更新3、key字段内容是否超1024 |
| -1050 | TCAPLUS_INDEX_ERR_SEND_TO_INDEX_SERVER_FAILED_FOR_NO_CONNECTOR | 分布式索引查询失败 | Y | 请先检查是否设置分布式索引（全局索引），一般是表没有配分布式索引，但有分布式索引查询 |
| -1054 | ZoneIdNotExist | zoneid不存在（go api错误码） | N | 检查zoneid信息是否正确 |
| -1280 | GEN_ERR_ECMGR_DUPLICATED_ERROR_CODE | 错误码表初始化失败，定义了重复的错误码 | N | TcapErrCodeInit函数多线程调用不安全，可能有失败的风险。把TcapErrCodeInit放到主线程初始化，或则加个同步锁 |
| -1293 | SVR_ERR_FAIL_RECORD_EXIST | insert的记录已存在 | Y | |
| -1297 | TCAPROXY_ERROR_SYSTEM_ERROR | PROXY异常 | N | 可能是proxy的transaction或action资源耗尽（可通联系tcaplus helper过proxy日志确认），可以通过proxy日志进一步确认 |
| -1299 | API_ERR_FIELD_NOT_EXSIST | 访问的字段不存在， 请确定字段名拼写正确 | Y | 建议查看表定义，确认表字段是否已经被定义。 |
| -1303 | DTR_ERR_APP_IS_NOT_FOUNT | dir找不到对应的app | Y | 1.检查app id是否正确2.检查dir地址是否正确 |
| -1310 | TableNotExist | 表不存在 | N | 请业务侧检查表是否存在或者表添加是否已经完成 |
| -1549 | SVR_ERR_FAIL_INVALID_FIELD_NAME | 访问的字段不存在， 请确定表结构已更新到后端 | Y | 访问的字段非法：1、检查字段名是否正确；2、确认是否本地更新了表结构，但未在Tcaplus系统上变更；3、检查SetFieldName操作是否指定了错误的字段，只能设置value字段；4、可以联系DBA或者Tcaplus_Helper从后台日志中搜索给出报错的字段名； |
| -1555 | API_ERR_FIELD_TYPE_NOT_MATCH | 字段值的数据类型与其定义类型不匹配，如某个Key字段的类型是int8，当尝试调用GetKeyFloat获取该字段的值，建议查看表定义，确认字段数据类型。 | Y | |
| -1792 | GEN_ERR_TABLE_READONLY | 表处于只读模式，请检查RCU, WCU或容量是否超出用户设定的阈值 | Y | 在腾讯云模式上可能遇见的较多，主要是项目组设置的表的QPS，读写容量值小于了实际的值 |
| -1805 | SVR_ERR_FAIL_VALUE_OVER_MAX_LEN | 记录超过最大长度，序列化后不能超过10MB | Y | 非list表的话，就看下是不是超过单个字段设置的最大长度了。list表，确认该表定义的单个key下最大的元素个数 |
| -1811 | API_ERR_PARAMETER_INVALID | 参数错误返回，一般在api调用的接口，设置的参数不合理返回 | Y | 1 参照接口.h注释排查参数是否设置正确2 提供接口和参数，联系tcaplus协助定位 |
| -2048 | GEN_ERR_TABLE_READ_DELETE | 容量超限， 可读可删， 但不能写 | Y | 在腾讯云模式上可能遇见的较多，主要是项目组设置的表的QPS，读写容量值小于了实际的值 |
| -2061 | SVR_ERR_FAIL_INVALID_FIELD_TYPE | 表字段类型错误 | Y | 项目组确定gameserver和Tcaplus使用的表XML是否一致。字符类型非法，包括：1、设置的字段长度与表定义中该字段长度不相等，比如int类型，字段长度必须是4；2、不支持的字段类型；项目组请先检测gamesvr和tcaplus使用的表xml是否一致 |
| -2067 | API_ERR_OPERATION_TYPE_NOT_MATCH | 1 表类型和命令字不匹配。比如generic表用了list表的命令字2 标记位不支持，SetLimit，SetFlag等设置标记位与命令不匹配 | Y | 1 表类型和命令字不匹配，是否是list，generic表的命令错误使用2 request设置的标记位不支持当前命令，可以忽略该错误 |
| -2304 | GEN_ERR_ACCESS_DENIED | 表处于拒绝访问状态。常见于腾讯云环境 | N | 1.可能是表的实际读写量超加了指定的QPS, 确认是否加表时指定了QPS。2.检查一下表是否设置了禁止读写，可以联系dba确认如果没解决请联系管理员。 |
| -2317 | SVR_ERR_FAIL_SYNC_WRITE | tcapsvr_fail_sync_write | N | |
| -2323 | API_ERR_PACK_MESSAGE | setdata时打包失败 | Y | 本地表meta和线上是否一致排查tdr打包规则，可联系tcaplus协助定位 |
| -2560 | GEN_ERR_INVALID_ARGUMENTS | 参数错误，请检查api日志或联系管理员 | N | 1.请检查本地和线上表结构是否一致；2.一般是PB API用的错误码： a. 初始化传入参数非法，或者配置错误 b. GetMessageOption获取的option先前没有调用SetMessageOption去设置 c. 关注pb api的错误日志如果是ServiceAPI的错误，一般会有error日志，后端通信模块一般不会将这个错误透传给ServiceAPI，如果有，请联系管理员 |
| -2573 | SVR_ERR_FAIL_WRITE_RECORD | 写引擎错误，请联系管理员 | Y | 1、单个引擎文件是否超过256GB大小；2、磁盘是否出现异常，比如磁盘只读，或者存在坏道；3、查看具体的日志，获取更详细的错误信息； |
| -2579 | API_ERR_UNPACK_MESSAGE | GetData时，响应消息解包失败 | N | 排查tdr解包规则本地表meta和线上是否一致SetKey/SetValue和SetData是否混用 |
| -2583 | DIR_ERR_IS_NOT_THIS_ZONE_API | dir地址错误 | Y | 1、请检查dir地址配置和对应的zone是否正确2、单个api访问，只能访问一个set内的不同zone，而不能跨set集群访问3、请检查对应的zone是否有可用的proxy4、请检查该游戏区是否加表，并确认加表单据成功执行 |
| -2816 | GEN_ERR_UNSUPPORT_OPERATION | 不支持的操作，请联系管理员 | Y | 某些函数针对某些命令字不支持List表不支持设置ttlList表不支持获取ttl对于条件查询与更新，只支持包括（TCAPLUS_API_GET_REQ、TCAPLUS_API_GET_BY_PARTKEY_REQ、TCAPLUS_API_REPLACE_REQ、TCAPLUS_API_UPDATE_REQ、TCAPLUS_API_DELETE_REQ、TCAPLUS_API_PB_FIELD_INC_REQ、TCAPLUS_API_PB_FIELD_GET_REQ、TCAPLUS_API_UPDATE_ITEM_REQ、TCAPLUS_API_LIST_GETALL_REQ、TCAPLUS_API_LIST_DELETE_BATCH_REQ、TCAPLUS_API_LIST_REPLACE_REQ、TCAPLUS_API_LIST_GET_REQ、TCAPLUS_API_LIST_DELETE_REQ）PB表支持的命令字只包括（tcaplusdb::Head_TypeCmd_DATA_CMD_ADD_REQ、tcaplusdb::Head_TypeCmd_DATA_CMD_GET_REQ、tcaplusdb::Head_TypeCmd_DATA_CMD_DELETE_REQ、tcaplusdb::Head_TypeCmd_DATA_CMD_UPDATE_REQ、tcaplusdb::Head_TypeCmd_DATA_CMD_REPLACE_REQ、tcaplusdb::Head_TypeCmd_DATA_CMD_INDEXGET_REQ、tcaplusdb::Head_TypeCmd_CTRL_CMD_CMP_TABLE_META_REQ、tcaplusdb::Head_TypeCmd_CTRL_CMD_LIST_TABLE_META_REQ）PB 协程API调用SetMessageOption的时候，如果设置MESSAGE_OPTION_MESSAGE_INVALID 或MESSAGE_OPTION_MESSAGE_INVALID 时无效 |
| -2823 | ENG_ERR_ENGINE_ERROR | 引擎错误，请联系管理员 | N | |
| -2829 | SVR_ERR_FAIL_DELETE_RECORD | 删除引擎记录失败，请联系管理员 | N | 出现删除记录失败，需要看下硬件上磁盘坏道问题 |
| -3072 | GEN_ERR_NOT_ENOUGH_MEMORY | 内存不足 | N | 一般是业务压测过载1.svr的autobuffer申请内存失败2.PROXY内存不足请降低压力或者联系DBA扩容 |
| -3079 | ENG_ERR_DATA_ERROR | 数据错误，请联系管理员 | N | |
| -3085 | SVR_ERR_FAIL_DATA_ENGINE | SetFieldName操作指定了错误的字段 | Y | 该错误码主要是在读取记录时发生的，包含的错误类型很广泛，比如：1、在xxxbypartkey时，注意看是否把key字段设置SetFieldNames里了，看设置的value字段是否合法2、反序列化失败3、内存不够4、加锁失败；5、读取hash桶失败等；因此，需要登录到svr机器上，查看具体的错误详情； |
| -3089 | PROXY_ERR_ROUTE_MSG | 路由错误 | N | 1.检查相关app/zone/表是否加上，可在控制台“单据中心”页面检查是否有加表单据未完成。2.业务侧getkey getvalue时，keybuff为空，找不到key无法路由报错不是如上情况，请联系Tcaplus检查proxy是否在线及相关日志 |
| -3091 | API_ERR_OVER_MAX_RECORD_NUM | api插路由失败，一般不会出现，出现请联系tcaplus排查 | N | |
| -3328 | GEN_ERR_NOT_SATISFY_INSERT_FOR_SORTLIST | SortList表 存储引擎内部错误，请联系Tcaplus_Helper排查 | N | 内部Meta维护错误排序失败不属于sortlist表元素写满，符合sortlist的淘汰规则但淘汰失败的情况 |
| -3341 | SVR_ERR_FAIL_RESULT_OVERFLOW | 字段值大小超过其定义类型的限制 | Y | 询问项目组是否符合预期，属于正常的业务逻辑，比如有些项目组会按照找个逻辑设置最大值和最小值 |
| -3347 | API_ERR_INVALID_COMMAND | 回包的命令不匹配 | N | 可能原因有：1、在请求中设置了当前接口不支持的命令字；2、请求和响应对象中的部分函数只在使用特定命令字时才可调用，如果使用不当，也会报该错，比如response.GetTableRecordCount函数，只有当前命令字是TCAPLUS_API_GET_TABLE_RECORD_COUNT_RES才可以调用。 |
| -3603 | API_ERR_NO_MORE_RECORD | FetchRecord时，响应包中已经没有记录了 | Y | 一般是推荐项目组先判断GetResult，再判断GetRecordCount，再for循环的FetchRecord |
| -3859 | API_ERR_OVER_KEY_FIELD_NUM | 超过最大key个数限制，当前最大8个key，list表7个 | Y | 1、key数量超过，页面加表会拦截2、一般在setkey接口出现该错误，请排查setkey调用的次数，是否超过key数量限制 |
| -3853 | SVR_ERR_FAIL_INVALID_SUBSCRIPT | limit或者offset参数错误 | N | 按照offset和limit拉取时，传的参数不对 |
| -4109 | SVR_ERR_FAIL_INVALID_INDEX | list数据类型元素下标超过范围 | Y | 需要业务检测是不是传递的idx不正确，一般推荐的是listgetall返回的idx作为下次操作的idx |
| -4115 | API_ERR_OVER_VALUE_FIELD_NUM | value字段数量超限，generic表限制数为128, List表限制数：1273.46.0版本增大到generic表限制数为256, List表限制数：255 | Y | 请根据版本排查数量是否超限，超过限制可下载最新版本升级 |
| -4119 | DIR_ERR_IS_NOT_IN ZONES_WHITE LIST | GameServer 客户端ip不在白名单 | N | 联系dba进行GameServer白名单配置添加后访问 |
| -4365 | SVR_ERR_FAIL_OVER_MAXE_FIELD_NUM | 超过最大字段个数 | Y | 需要根据Tcaplus API版本里来确认支持的字段个数 |
| -4371 | API_ERR_OBJ_NEED_INIT | 1 API未初始化就调用数据库请求2 需要操作的表未RegisterTable | Y | 1、确认表是否有加上2、加表后，API侧RegistTable是否有写上3、gameserver在运行期间删除了表再新增表，需要重新RegistTable |
| -4377 | COMMON_ERR_INVALID_EXPR_SYNTAX | 条件或者操作语句的语法错误 | N | 请检查对应操作语法是否正确 |
| -4621 | SVR_ERR_FAIL_MISS_KEY_FIELD | 请求缺少主键字段或索引字段 | Y | 可能导致的原因：1、TCAPLUS_CMD_GET_BY_PARTKEY_REQ等查询，如果key不全会报SVR_ERR_FAIL_MISS_KEY_FIELD2、InsertByPartKey的时候，key不全也会报SVR_ERR_FAIL_MISS_KEY_FIELD； |
| -4627 | API_ERR_INVALID_DATA_SIZE | 数据大小不对，通常是用户的本地表定义和服务端不一致。建议检查：1、Tcaplus后台2、业务编译的该表的.h .cpp3、业务启动时加载的该表的tdr文件 | Y | 需要业务确认，数据大小不对，建议先检查本地表定义和服务端的表定义是否一致，再检查业务代码是否设置的请求参数是否超限了。具体原因可能有：1、请求中设置的目标表名长度超过了限制（32）；2、请求中设置的用户数据长度超过了限制（1024）；3、请求中设置的Key字段值大小超过了限制（1024B）；4、请求中性能测试数据的大小超过了限制（256B）；5、请求中字段值的大小超过了表定义中定义的字段值最大大小；6、Batch请求中所指定的所有字段的值的大小总和超过了限制（10300000B）。 |
| -4633 | COMMON_ERR_INVALID_ARRAY_INDEX | 无效的数组下标，如部分字段查询时，如"array_fields[10]"查询下标为10的元素，但数组大小小于11时会报错 | Y | 检查下标填写是否合法，检查是否超过数组大小，对应的字段是否数组类型。 |
| -4883 | API_ERR_INVALID_ARRAY_COUNT | 数组大小无效 | Y | 表定义里refer大于count了，需要业务检测下 |
| -4889 | COMMON_ERR_INVALID_FIELD_NAME | 无效字段名 | N | 请检查本地表定义和线上表定义字段是否一致 |
| -5137 | PROXY_ERR_PACK_MSG | 打包失败 | N | |
| -5139 | API_ERR_INVALID_UNION_SELECT | 无效的union的select | Y | Union定义里，select对应的数据需要存在，不存在就报错 |
| -5145 | COMMON_ERR_INVALID_EXPR_TYPE | 一般是条件过滤或者更新时报错，数值类型不匹配，如条件"name > 10"要求name字段必须是数值类型 | Y | 检查表定义的类型，数值比较或者赋值的左右值类型是否匹配 |
| -5393 | PROXY_ERR_SEND_MSG | 发送消息失败 | Y | |
| -5395 | API_ERR_MISS_PRIMARY_KEY | 请求中缺少主键 | Y | 建议检查业务代码，确认是否为请求设置了所有主键字段值。 |
| -5649 | PROXY_ERR_ALLOCATE_MEMORY | 内存不足 | Y | 可能是事务类型操作（包括batchget这类批量操作等）配置的内存达到上限，小概率是其他内存不足原因 |
| -5651 | API_ERR_UNSUPPORT_FIELD_TYPE | PB不支持的字段类型，比如repeat类型 | N | 排查pb和restproxy字段类型 |
| -5905 | PROXY_ERR_PARSE_MSG | 解析消息失败 | N | tcaproxy解包失败 |
| -5907 | API_ERR_ARRAY_BUFFER_IS_SMALL | 内存太小 | N | |
| -6157 | SVR_ERR_FAIL_LIST_FULL | list表元素个数超过定义范围,请设置元素淘汰 | Y | |
| -6161 | PROXY_ERR_INVALID_MSG | 无效的消息 | N | 一般客户端不会返回该错误码，若tcaproxy刷该日志，可能是安全扫描 |
| -6412 | SVR_ERR_FAIL_LOW_VERSION | 版本太低 | N | |
| -6417 | PROXY_ERR_FAILED_PROC_REQUEST_BECAUSE_NODE_IS_IN_SYNC_STASUS | 有损搬迁，部分命令不支持，当前主要是无损搬迁，不会遇到该问题 | Y | |
| -6669 | SVR_ERR_FAIL_HIGH_VERSION | 版本太高 | Y | Tcaplus API的版本高于了tcaproxy的版本，解决方式：1、项目组降低service api的版本；2、联系DBA或者Tcaplus_Helper升级tcaplus后台版本； |
| -6673 | PROXY_ERR_KEY_FIELD_NUM_IS_ZERO | 没有key字段 | Y | 需要业务检查业务代码 |
| -6925 | SVR_ERR_FAIL_INVALID_RESULT_FLAG | result_flag设置错误，请参考SDK中result_flag说明 | Y | |
| -6929 | PROXY_ERR_LACK_OF_SOME_KEY_FIELDS | 请求中缺少key字段 | Y | |
| -7181 | SVR_ERR_FAIL_PROXY_STOPPING | 接入层正在停止，业务无需关注，API或自动切换新的接入层 | N | 只是在tcaproxy安全退出时遇见 |
| -7185 | PROXY_ERR_FAILED_TO_FIND_NODE | 找不到路由节点，请联系管理员 | N | 找不到路由节点，或者可能是表被删除，请联系管理员 |
| -7437 | SVR_ERR_FAIL_SVR_READONLY | 存储层只读，通常磁盘写满或在进行主备切换 | Y | 1、如果只是非常短暂出现，则项目组无需关注2、如果持续出现，那么需要联系DBA或者Tcaplus_Helper进行处理 |
| -7441 | PROXY_ERR_INVALID_COMPRESS_TYPE | 不支持的压缩类型 | N | 目前是支持snappy |
| -7443 | API_ERR_INCOMPATIBLE_META | 不兼容的表结构， 请检查本地表结构和服务端表结构是否兼容。 | Y | 确认下gameserver使用的表定义格式的版本号小于等于Tcaplus使用的表定义格式。建议检查客户端表定义和服务端表定义是否兼容。1、检查客户端使用的表定义的版本号是否小于等于服务端的表定义，要求客户端使用的表定义的版本号是否要小于等于服务端的表定义；2、确认客户端在使用高版本的表定义之前，已经将服务端的表定义变更到相应版本或者更高版本。 |
| -7669 | API_ERR_PACK_ARRAY_DATA | setdata时打包数组失败 | Y | 排查数组的refer设置是否正确，count有没有超限；本地表meta和线上是否一致 |
| -7693 | SVR_ERR_FAIL_SVR_READONLY_BECAUSE_IN_SLAVE_MODE | 请求发向存储层备节点，可能是正在主备切换。若长时间返回该错误码，请联系管理员 | Y | 该错误表明主从切换有损，需要继续跟进 |
| -7697 | PROXY_ERR_REQUEST_OVERSPEED | 请求速度超过配额 | Y | 腾讯云模式下比较多，项目组设置的QPS低于实际使用的QPS |
| -7949 | SVR_ERR_FAIL_INVALID_VERSION | 请检查乐观锁，请求记录版本号与实际记录版本号不一致 | Y | 多个请求在写，但是设置了只有1个请求写成功的，故其他请求就报错了。项目组要确认需求：1、N个请求，N次写成功，这个不需要乐观锁2、N个请求，第一次写成功，其余失败，这个就需要使用乐观锁 |
| -7953 | PROXY_ERR_SWIFT_TIMEOUT | 接入层超时 | Y | 1.batchget场景下，tcaproxy--> tcapsrv--> tcaproxy大于1s，需要跟进问题，请提供项目组app zone 2.batch操作，record在SetKey SetValue之后，需调用record的Pack方法打包 |
| -7955 | API_ERR_PACK_UNION_DATA | setdata时union打包失败 | N | 本地表meta和线上是否一致排查tdr打包规则，可联系tcaplus协助定位 |
| -8205 | SVR_ERR_FAIL_SYSTEM_ERROR | 存储层内部错误，请联系管理员 | N | |
| -8209 | PROXY_ERR_SWIFT_ERROR | 接入层事务非超时类错误，请联系管理员 | N | |
| -8211 | API_ERR_PACK_STRUCT_DATA | setdata时struct打包失败 | Y | 本地表meta和线上是否一致如果已经确认meta是一致的，如下两个概率比较大：1. 数组类型的元素其字符串长度超过了预定最大长度2. string/bytes的长度超过了meta指定的长度排查tdr打包规则，可联系tcaplus协助定位 |
| -8461 | SVR_ERR_FAIL_OVERLOAD | 存储层过载，请联系DBA或者Tcaplus_Helper进行排查 | N | 主线程将请求转发给工作线程时，由于消息队列满了，导致转发失败，一般原因：1、工作线程处理较慢，可以确认一下工作线程是否有slow日志2、磁盘性能是否到瓶颈 |
| -8465 | PROXY_ERR_DIRECT_RESPONSE | 接入层直接回包， 相当于不走业务逻辑，通常用于测试API | N | |
| -8467 | API_ERR_UNPACK_ARRAY_DATA | GetData时，数组解包失败 | Y | 排查tdr解包规则，refer是否正确，count是否超限；本地表meta和线上是否一致；SetKey/SetValue和SetData是否混用 |
| -8717 | SVR_ERR_FAIL_NOT_ENOUGH_DADADISK_SPACE | 存储层数据盘磁盘空间不足 | Y | |
| -8721 | PROXY_ERR_INIT_TLOG | 初始化日志模块失败 | N | |
| -8723 | API_ERR_UNPACK_UNION_DATA | GetData时，union解包失败 | Y | 排查tdr解包规则，union的selector是否正确本地表meta和线上是否一致SetKey/SetValue和SetData是否混用 |
| -8973 | SVR_ERR_FAIL_NOT_ENOUGH_ULOGDISK_SPACE | 存储层binlog流水盘磁盘空间不足 | Y | 需要删除下Ulog所在的磁盘上无效的文件，减少磁盘占用 |
| -8979 | API_ERR_UNPACK_STRUCT_DATA | GetData时，struct解包失败 | Y | 排查tdr解包规则本地表meta和线上是否一致SetKey/SetValue和SetData是否混用 |
| -9229 | SVR_ERR_FAIL_UNSUPPORTED_PROTOCOL_MAGIC | 内部错误，不支持的接入层协议magic | N | 可以去掉这个错误码，目前代码中已经没有返回这个错误码的地方了 |
| -9233 | PROXY_ERR_REQUEST_ACCESS_CTRL_REJECT | 接入层拒绝访问 | N | 一般有限流控制导致返回此错误码，例如测试集群有限流控制，如果用共享资源，qps有限制；具体请联系DBA或者Tcaplus _Helper进行处理 |
| -9235 | API_ERR_INVALID_INDEX_NAME | 本地索引不存在 | Y | 需要查看本地索引定义，可能原因有：1、构造请求时传入的索引名为NULL，或者为空字符串2、构造请求时传入的索引名，在表的元数据中未定义 |
| -9485 | SVR_ERR_FAIL_UNSUPPORTED_PROTOCOL_CMD | 不支持的命令字 | N | |
| -9489 | PROXY_ERR_NOT_ALL_NODES_ARE_IN_NORMAL_OR_WAIT_STATUS | 遍历请求返回该错误码，因为该表处于搬迁状态 | N | 目前使用无损搬迁模式，如出现请联系Tcaplus |
| -9491 | API_ERR_MISS_PARTKEY_FIELD | 缺少partkey字段 | N | 请求（如get by part key请求，delete by part key请求等）中缺少索引字段，建议检查业务代码，确认是否为请求设置了所有目标本地索引的索引字段值。需要项目组查看代码 |
| -9745 | PROXY_ERR_ALREADY_CACHED_REQUEST_TIMEOUT | 路由变更时，cache的请求已超时 | Y | 遇见该问题，说明是有损的，需跟进 |
| -9747 | API_ERR_ALLOCATE_MEMORY | 分配内存失败 | N | 建议检查客户端的内存使用情况，确保有足够内存供SDK使用。 |
| -9997 | SVR_ERR_FAIL_MERGE_VALUE_FIELD | 合并value字段失败，内部错误，请联系管理员 | N | 二级字段及其以上字段出现兼容问题 |
| -10001 | PROXY_ERR_FAILED_TO_CACHE_REQUEST | 路由变更时，cache请求失败 | N | 请求缓存失败，一般是缓存满 |
| -10253 | SVR_ERR_FAIL_CUT_VALUE_FIELD | 合并value字段失败，内部错误，请联系管理员 | N | |
| -10257 | PROXY_ERR_NOT_EXIST_CACHED_REQUEST | 路由变更时，不存在cache请求 | N | 请求还没有被缓存在cache中 |
| -10259 | API_ERR_MISS_BINARY_VERSION | 内部错误，二进制字段缺失版本 | N | SetData/GetData时，binary字段前有2B的版本号 |
| -10509 | SVR_ERR_FAIL_PACK_FIELD | 内部错误，打包字段失败，请联系管理员 | N | |
| -10513 | PROXY_ERR_FAILED_NOT_ENOUGH_CACHE_BUFF | 路由变更时，buff不足 | N | 内存不足导致 |
| -10765 | SVR_ERR_FAIL_UNPACK_FIELD | 存储层解包失败 | N | |
| -10769 | PROXY_ERR_FAILED_PROCESS_CACHED_REQUEST | 接入层处理缓存的请求失败 | N | 请求已经cache了，再次请求会产生这个错误 |
| -10771 | API_ERR_INVALID_RESULT_FLAG | 无效的result flag | Y | |
| -11021 | SVR_ERR_FAIL_LOW_API_VERSION | api版本太低，请升级api | N | |
| -11027 | API_ERR_OVER_MAX_LIST_INDEX_NUM | 批量操作记录数超限，最多支持批量1024条记录 | N | 减少批量操作记录数 |
| -11277 | SVR_ERR_COMMAND_AND_TABLE_TYPE_IS_MISMATCH | 操作表的方法不存在 | Y | 请求命令字与表类型不匹配，比如ListReplace请求只适用于list表，但是却去操作generic表； |
| -11283 | API_ERR_INVALID_OBJ_STATUE | 未初始化， 通常出现在遍历请求中 | N | 1.需要项目组看下代码，目前主要是遍历器的状态错误，如尝试遍历器未初始化等。在调用遍历器的接口时，会检查遍历器当前的状态是否正确，例如调用Start函数时，当前遍历器要求处在READY状态。 2.请检查是否并发遍历，一个sdk client实例对象同一个表只能有一个遍历器。 |
| -11533 | SVR_ERR_FAIL_TO_FIND_CACHE | 存储层未找到数据分片，内部错误，请联系管理员 | N | 数据分片不存在，需要具体看日志进行排除，比如请求中访问的数据分片是否已经被删除了 |
| -11537 | PROXY_ERR_SWIFT_SEND_BUFFER_FULL | 发送缓冲区已满， API处理响应太慢 | Y | 需要跟进gameserver端调用Tcaplus API的收包代码的情况 |
| -11539 | API_ERR_INVALID_REQUEST | 无效的请求 | N | 可能原因有：1、非法的请求，比如Get请求没有指定记录的Key、batchget没有addrecord等，建议参照用户文档检查请求是否合法2、Restful接口调用的请求缺少必要的Header，ErrMsg中有详细的提示，建议检查Restful请求是否合法3、Proxy为批量操作创建事务失败等场景，联系DBA确认问题原因 |
| -11789 | SVR_ERR_FAIL_TO_FIND_META | 存储层未找到表定义， 内部错误，请联系管理员 | Y | 表元数据不存在，需要具体看日志进行查找，比如请求中访问的表是否是已经删除掉的表。如果是 TDR Blob 内嵌 PB 部分读写（PB_FIELD_GET / PB_FIELD_SET / PB_BATCH_FIELD_GET）请求返回该错误，说明后端版本过旧，需要升级到 Tcapsvr 3.73.0 2026-10-10 以后的版本 |
| -11793 | PROXY_ERR_REQUEST_OVERLOAD_CTRL_REJECT | 接入层过载 | N | 请求量超过proxy的处理能力 |
| -12045 | SVR_ERR_FAIL_TO_GET_CURSOR | 存储层获取遍历游标失败， 可能是同时进行的遍历请求太多，通常不会遇到 | N | |
| -12049 | PROXY_ERR_SQL_QUERY_MGR_IS_NULL | SQL查询管理器创建失败 | N | 一般是内存不足或ES服务连接不成功 |
| -12051 | API_ERR_TABLE_NAME_MISSING | restproxy请求未设置表名称 | N | 请排查restproxy请求参数 |
| -12301 | SVR_ERR_FAIL_OUT_OF_USER_DEF_RANGE | 超过用户定义的范围 | N | 项目组对某个字段(整型或者浮点型) 的值进行增加或者减少，排查：1、比如increase操作，增加或者减少后的值超过或者低于用户自定义的范围2、比如用户自定义字段A的访问为[10,20]，字段A当前的值为15，此时请求中要求对该字段增加6，那么增加后的值就超过了20，会返回该错误3、或者用户请求中要求对该字段减少6，那么减少后的值少于10，也会返回该错误 |
| -12305 | PROXY_ERR_SQL_QUERY_INVALID_SQL_TYPE | 无效的sql请求 | N | SQL不合法，或者SQL查询的类型后端不支持 |
| -12307 | API_ERR_SOCKET_SEND_BUFF_IS_FULL | api发送缓冲区满 | Y | 1、用户发包太快，包量太大2、排查网络是否到瓶颈，发包太慢3、排查后端proxy数量太少，收包太慢，到瓶颈 |
| -12557 | SVR_ERR_INVALID_ARGUMENTS | 内部参数错误 | N | |
| -12561 | PROXY_ERR_GET_TRANSACTION_FAILED | 分配失败失败，请联系管理员增加事务并发的配置 | N | 一般是事务超时释放了，但后端消息来了找不到对应的事务 |
| -12563 | API_ERR_INVALID_MAGIC | magic不对，通信出现问题，若一直有该问题，请联系管理员 | N | 协议上magic不对，需要跟进代码 |
| -12817 | PROXY_ERR_ADD_TRANSACTION_FAILED | 分配失败失败，请联系管理员增加事务并发的配置 | N | 事务是预分配的，在swift的里，如果用量超过配置的值，就会报这种错误 |
| -12819 | API_ERR_TABLE_IS_NOT_EXIST | 操作的表不存在 | Y | 一般在Register表时出错，排查页面上的表是否加成功，有可能在审核状态，请联系dba审核 |
| -13069 | SVR_ERR_NULL_CACHE | 不存在该数据分片 | N | |
| -13073 | PROXY_ERR_QUERY_FROM_INDEX_SERVER_FAILED | 查询全局索引失败 | N | 1.全局索引未配置，请配置完后再使用2.如果已配置全局索引，可能是ES过载，请联系DBA或者Tcaplus_Helper排查 |
| -13075 | API_ERR_SHORT_BUFF | restapi限制请求响应body为10M；目前http请求限制了整个包的大小为 10M | N | 请排查restproxy请求大小 |
| -13329 | PROXY_ERR_QUERY_FROM_INDEX_SERVER_TIMEOUT | 查询全局索引超时 | N | tcaplus服务后端在指定的时间内没有返回响应，有可能是服务过载、网络不通或服务未开启 |
| -13331 | API_ERR_FLOW_CONTROL | api_flow_control | N | |
| -13581 | SVR_ERR_METALIB_VERSION_LESS_THAN_ENTRY_VERSION | the metalib version in request is less than entry version | N | |
| -13585 | PROXY_ERR_QUERY_FOR_CONVERT_TCAPLUS_REQ_TO_INDEX_SERVER_REQ_FAILED | 解析全局索引的sql语句失败 | N | 一般是用户请求侧的SQL语句不合法，导致后端解析失败 |
| -13587 | API_ERR_COMPRESS_SWITCH_NOT_SUPPORTED_REGARDING_THIS_CMD | 对不支持协议压缩的命令调用的协议压缩SetCompressSwitch | N | 当前支持设置协议压缩的命令字有：1. TCAPLUS_CMD_GET_REQ2.TCAPLUS_CMD_BATCH_GET_REQ3.TCAPLUS_CMD_GET_DURING_MOVE_REQ |
| -13837 | SVR_ERR_INVALID_SELECT_ID_FOR_UNION | 内部错误，请联系管理员 | N | |
| -13841 | PROXY_ERR_QUERY_INDEX_FIELD_NOT_EXIST | 索引字段不存在 | N | SQL中查询的语句中指定的字段没有在tcaplus的表定义中找到。需要确认客户端的字段是否在tcaplus中有定义 |
| -13843 | API_ERR_FAILED_TO_FIND_ROUTE | 后台网络异常，请求无法发送成功，如持续存在请联系管理员 | Y | 找不到路由，gameserver找不到可用的tcaproxy，需要跟进日志。1、SDK与服务端网络异常，SDK找不到可用的Proxy服务器，请求无法发送成功2、如果用户断点调试可能会导致tcaproxy心跳异常，返回此错误码3、如果该问题持续存在，需要联系DBA或者Tcaplus_Helper，检查Proxy服务器是否运行正常，以及客户端到服务端的网络是否正常 |
| -14093 | SVR_ERR_CAN_NOT_FIND_SELECT_ENTRY_FOR_UNION | 对于union字段类型，服务端获取select entry失败 | N | |
| -14097 | PROXY_ERR_THIS_SQL_IS_NOT_SUPPORT | 不支持的SQL | N | 当前的SQL类型proxy还未支持 |
| -14099 | API_ERR_OVER_MAX_PKG_SIZE | 操作的单条记录打包后超过10M | Y | 记录大小有限制，减小记录大小。需要根据版本来确认单条记录大小限制，3.40.0之后支持10M，之前的最大1M |
| -14353 | PROXY_ERR_NO_SUCH_APPID | 接入层认证失败，未找到该业务认证信息 | N | tcaplus接入层未缓存指定app信息，常见于系统内部逻辑错误 |
| -14605 | SVR_ERR_TCAPSVR_PROCESS_NOT_NORMAL | tcapsvr process in abnormal | N | |
| -14609 | PROXY_ERR_NO_APP_USER_PASSWD | 接入层找不到用户认证信息 | N | tcaplus接入层未缓存指定app的密码信息，常见于系统内部逻辑错误 |
| -14865 | PROXY_ERR_NO_APP_USER_PASSWD_RECORD | 接入层找不到用户认证信息 | N | tcaplus接入层未缓存指定app的密码信息，常见于系统内部逻辑错误 |
| -15117 | SVR_ERR_INVALID_ARRAY_COUNT | 无效的数组大小 | Y | 需要查看TDR规则，数组大小非法，比如表定义中该数组字段最大大小为10，但是请求中传递的refer count大小为12 |
| -15121 | PROXY_ERR_NO_APP_USER_OPT | 接入层找不到用户认证信息 | N | |
| -15123 | API_ERR_ADD_RECORD | failed to add a new record into request | N | |
| -15373 | SVR_ERR_REJECT_REQUEST_BECAUSE_ROUTE_IN_REJECT_STATUS | 拒绝请求，svr处于搬迁状态，路由错误。 | N | |
| -15377 | PROXY_ERR_NO_APP_USER_OPT_RECORD | 接入层未找到用户认证信息 | N | tcaplus接入层未缓存指定app的用户密码信息，常见于系统内部逻辑错误 |
| -15379 | API_ERR_ZONE_IS_NOT_EXIST | 操作的zoneid不存在 | N | 请排查:1、页面上改app是否存在该zone2、tcaplus的环境是否连错 |
| -15635 | API_ERR_TRAVERSER_IS_NOT_EXIST | 收到包时，遍历器已经销毁或停止，一般不会返回给用户，可忽略 | N | |
| -15885 | SVR_ERR_FAIL_INVALID_FIELD_VALUE | 无效的字段值 | N | |
| -16141 | SVR_ERR_FAIL_PROTOBUF_FIELD_GET | PB表GetRecord操作失败，请联系管理员 | Y | 请先检查：1.记录是否存在2.检查一下是否缺少哪个字段 |
| -16147 | API_ERR_INSTANCE_INIT_LOG_FAILURE | 初始化日志模块失败 | N | 建议检查日志配置文件是否正确 |
| -16389 | TXHDB_ERR_INVALID_VALUE_DATABLOCK_NUM | 存储层value块个数异常，请联系管理员 | N | |
| -16397 | SVR_ERR_FAIL_PROTOBUF_VALUE_BUFF_EXCEED | PB表非主键字段值超过限定大小(256KB) | Y | 需要根据版本确定单个value字段大小 |
| -16403 | API_ERR_CONNECTOR_IS_ABNORMAL | 连接异常 | N | |
| -16653 | SVR_ERR_FAIL_PROTOBUF_FIELD_UPDATE | PB表FieldSetRecord操作失败，或TDR Blob内嵌PB部分更新失败，请联系管理员 | Y | 先自查操作的字段是否已经在服务端存在；TDR Blob 内嵌 PB 部分更新还需检查 Blob 中是否为合法的 PB 编码、字段路径的类型是否与实际数据一致 |
| -16659 | API_ERR_WAIT_RSP_TIMEOUT | SDK收包超时 | N | 1.可以先看一下SDK日志，是否长时间没有调用SDK的RecvResponse函数导致的超时2.可能是服务端丢包了，比如send buffer full，请联系tcaplus进行排查 |
| -16901 | TXHDB_ERR_COMPRESSION_FAIL | 压缩失败 | N | |
| -16909 | SVR_ERR_FAIL_PROTOBUF_FIELD_INCREASE | PB表FieldIncRecord操作失败，请联系管理员 | Y | |
| -16915 | API_ERR_CONVERT_DIR_DOMAIN | api 解析dir域名解析失败 | Y | ping dir域名，尝试是否可以解析，可能原因有：1、域名不正确，或者不存在的域名2、客户端DNS配置错误3、dir地址是否填写正确，如漏写“tcp://xxx:9999”等 |
| -17157 | TXHDB_ERR_DECOMPRESSION_FAIL | 解压失败 | N | |
| -17165 | SVR_ERR_FAIL_PROTOBUF_FIELD_TAG_MISMATCH | PB表tag不匹配 | Y | 项目组gameserver端表定义和Tcaplus表定义是否一致 |
| -17171 | API_ERR_NET_THREAD_START_TIMEOUT | api等待网络线程启动失败 | N | 1、一般是cpu卡顿导致子线程启动慢2、网络线程拷贝主线程的日志句柄失败，导致启动失败；这种一般是tlog的clone失败导致；如果是先Fin再Init的，建议再Fini之后，日志句柄也销毁掉，重新生成下 |
| -17427 | API_ERR_DIR_CONNECT_FAILED | dir链接失败 | Y | 与所有Dir服务器都连接失败，建议telnet Dir服务器端口，看是否是通的，如果不通，可能原因有：1、检查一下dir地址是否正确；2、检查客户端到dir服务器的网络是否通；是否跨idc和dev访问，不能跨网络访问 3、联系DBA，检查dir服务器是否正常运行。 |
| -17683 | API_ERR_DIR_SIGNUP_FAILED | dir认证失败 | Y | 排查密码，可能原因有：1、找不到指定的app，或者app密码错误，建议检查app id或者app密码；2、当前客户端机器不在访问白名单中，需要联系DBA确认并加白名单；3、SDK版本高于Dir服务器的版本，或者低于最低版本要求，建议检查客户端版和服务端是否匹配；4、Dir没有找到相应的会话信息，建议重连。 |
| -17939 | API_ERR_DIR_GET_PROXYLIST_TIMEOUT | 从dir拉取proxy列表超时 | N | 排查dir模块，返回列表慢。建议1.先使用telnet检测客户端到Dir服务器的连通性，如果可以连通则重试；2.检查一下业务侧设置的timeout超时时间，比如是否为0，一般超时时间默认3s；3.请在OMS控制台检查对应游戏区下表已添加创建完成；如果不能连通或者重试问题依然存在，则联系DBA检查Dir服务器的运行情况。 |
| -18195 | API_ERR_PROXY_CONNECT_FAILED | API到proxy链接失败 | Y | 1、是否是网络限制，dev到idc是否开通策略，proxy迁移后是否再次开通2、telnet proxy的网络端口看是否能连上3、curl proxy的网络端口看是否有权限类的错误4、proxy连接数有3000的限制，客户端是否过多，联系tcaplus排查 |
| -18445 | SVR_ERR_FAIL_DOCUMENT_NOT_SUPPORT | 不支持Document类请求 | N | |
| -18451 | API_ERR_COMPARE_TABLE_META_FAILED | api和svr的meta对比失败 | Y | 比对本地和oms的表格是否一致 |
| -18701 | SVR_ERR_FAIL_PARTKEY_INSERT_NOT_SUPPORT | 不支持InsertByPartkey | N | |
| -18957 | SVR_ERR_FAIL_SQL_FILTER_FAILED | 分布式索引中，执行sql过滤失败 | N | |
| -33541 | TXHDB_ERR_ADD_LSIZE_EXCEEDS_MAX_TSD_VALUE_BUFF_SIZE | 内部错误，请联系管理员 | N | 压缩失败，请联系Tcaplus_Helper排查 |
| -34053 | TXHDB_ERR_TOO_BIG_KEY_BIZ_SIZE | key超过最大限制1KB | N | |
| -34309 | TXHDB_ERR_TOO_BIG_VALUE_BIZ_SIZE | value超过最大限制，10MB | N | |
| -34565 | TXHDB_ERR_INDEX_NO_EXIST | 索引不存在 | N | 请确认表定义中是否有该索引 |
| -39685 | TXHDB_ERR_FILE_EXCEEDS_LSIZE_LIMIT | 单数据分片超过256GB的最大限制，写入失败 | Y | 出现该问题时，需要扩容处理 |
| 269 | SVR_ERR_FULL_SORTLIST_CANT_INSERT | sortlist表中新插入的数据超过list元素最大个数，插入失败 | N | sortlist表中新插入的数据超过list元素最大个数，即使插入也会立即被淘汰，插入失败，返回此错误码 |
| -19863 | API_ERR_DROP_SUB_PKG | GetByPartKey/ListGetAll 分包丢包 | N | 大概率是用户收包不及时，包量大导致Proxy Buffer满丢包，可以联系tcaplus排查查看Proxy和Svr丢包监控和日志 |
| 537 | COMMON_ERR_ELEMENT_NOT_EXIST | 指定的元素不存在，如 TDR Blob 内嵌 PB 部分读写时指定的 map key 不存在，或部分更新 map 指定 key 时增量 PB 中缺少该 key。注意该错误码是正数 | N | 检查 map key 是否存在、增量 PB 中是否带了对应 key；删除 map 元素请使用 POP 路径。判断请求是否失败时使用 ret != 0，不要使用 ret < 0 |
| -3597 | SVR_ERR_FAIL_INVALID_OPERATION | 更新操作类型不正确，如 TDR Blob 内嵌 PB 部分更新请求携带了 operation 更新表达式 | N | TDR Blob 内嵌 PB 部分更新不支持 operation，请去掉 SetOperation 调用，用字段路径和增量 PB 表达更新内容 |