一、对接前先确认三件事

排错之前,先确认你手上的三个值是对的——绝大多数「莫名其妙」的报错,都是这三件事没对上:

  • 用户名:卡密通后台登录账号的用户名,接口地址 https://www.keyt.cn/kami/{用户名}/check.php 里的那一段,注意区分大小写。
  • 应用名:请求参数 app 的值,必须与后台创建的应用名一致,否则系统不认这张卡。
  • 签名密钥:后台「API 对接」里生成的密钥,用于计算 sign,泄露后任何人都能伪造验证结果,务必妥善保管。
💡
把这三个值集中放在代码的「配置区」并写清注释,对接时只改配置区,避免散落各处改漏。

标准请求格式如下(GET 请求,所有参数都要参与签名):

GET https://www.keyt.cn/kami/你的用户名/check.php?card=卡密&mac=机器码&app=应用名&heart=1&t=时间戳

正常返回:业务数据|sign=MD5(业务数据+签名密钥),其中业务数据形如 ok|valid|剩余天数|剩余分钟(终身卡为 ok|permanent);异常返回:error|错误码。

二、四个不返回错误码的常见坑

有些问题根本走不到错误码那一步,返回的是空白、超时或解析失败。这四个坑占了对接问题的一半:

现象最常见原因排查与修复
请求超时 / 404接口地址拼错,或用户名带空格/特殊字符未编码浏览器直接打开完整地址测试;用户名需 URL 编码
返回内容解析失败没按最后一个竖线 | 拆出 sign用 rsplit('|', 1) 从右往左拆,不要用 find 找第一个竖线
sign 校验不过MD5 拼接顺序错、密钥错、大小写错打印「业务数据原文 + 密钥」肉眼核对,MD5 输出统一 32 位小写
提示时间戳无效本机时间不准,或请求间隔超过防重放窗口同步系统时间;t 用当前秒级时间戳,不要缓存复用
⚠️
卡密通的 t 时间戳带防重放机制,同一个时间戳不能反复使用。每次请求都重新取当前时间,别把时间戳写死或缓存。

三、8 个错误码逐一详解

下面是卡密通接口返回的全部错误码速查表,后续每个错误码都有触发原因、排查步骤和解决办法:

错误码含义常见触发场景
missing_params缺少必要参数card / mac / app / t 有参数没传
invalid_card卡密无效卡密不存在、格式错、已被删除
expired卡密已过期天/周/月/年卡到期后继续使用
banned卡密被封禁违规使用被后台封禁
device_mismatch设备不匹配机器码与绑定时不一致(一机一码)
online_limit_reached在线数超限同一卡密同时在线设备超过上限
too_frequent请求过于频繁短时间内请求次数过多
system_locked系统锁定验证开关被关闭或系统维护中

1. missing_params 缺少参数

触发原因:card、mac、app、t 四个参数至少有一个没传或值为空。

排查步骤:把实际发出的完整 URL 打印出来,逐个核对参数名和值。特别注意 mac 机器码:如果采集逻辑返回空字符串,请求就会带上空的 mac。

解决办法:给机器码采集加兜底——采集失败时生成一个固定的随机标识并持久化保存,保证每次请求 mac 都有值且稳定。

2. invalid_card 卡密无效

触发原因:卡密不存在、格式错误,或卡密不属于当前 app 应用。

排查步骤:先看卡密是否复制完整(注意别把前后空格复制进去,建议 trim 一下);再到后台该应用下查询这张卡是否存在。

解决办法:输入框统一做去空格处理;提示用户卡密是「当前应用专属」,去错应用后台查不到。

3. expired 卡密已过期

触发原因:天卡/周卡/月卡/年卡到期后再次验证,或服务器时间比用户本机时间快导致提前判定过期。

排查步骤:在后台查看该卡密的到期时间,对比当前时间;若后台显示未到期却报 expired,检查用户电脑系统时间是否被改慢。

解决办法:正常提示「卡密已过期,请续费」;若怀疑用户改时间,配合心跳(超过 55 秒不心跳即退出)可大幅减少这类钻空子行为。

4. banned 卡密被封禁

触发原因:卡密因违规(倒卖、共用、恶意刷接口等)被你在后台封禁。

排查步骤:后台卡密列表里查看该卡状态是否显示已封禁,封禁原因和时间。

解决办法:误封就解封;确属违规的可保持封禁,并在公告接口(act=get_notice)里发布说明,让客户端能展示给用户。

5. device_mismatch 设备不匹配

触发原因:卡密已绑定机器码(一机一码),当前请求的 mac 与绑定值不一致。常见于:换电脑、重装系统、硬件更换、或机器码采集逻辑不稳定(每次生成的值不一样)。

排查步骤:把两次请求的 mac 值分别打印出来对比;检查采集逻辑用的是 CPU 序列号还是硬盘序列号,是否稳定可复现。

解决办法:正常换机走后台「解绑」流程;采集不稳定则改用更稳定的标识(如 CPU 序列号 + 磁盘卷序列号组合)。一机一码原理详见《一机一码绑定》一文。

6. online_limit_reached 在线数超限

触发原因:同一张卡密同时在线设备数超过后台设置的上限(默认 1 台,多设备场景可上调)。

排查步骤:在后台查看该卡密的在线设备列表,确认是不是被多台设备同时使用;或上一台设备异常退出导致会话未及时释放(心跳超时清理有延迟)。

解决办法:正常场景等心跳超时自动释放;频繁误报就把设备上限调到实际需要值,并配合 55 秒心跳让在线状态更实时。

7. too_frequent 请求过于频繁

触发原因:短时间(如 1 秒内)连续多次调用验证接口,被频率限制拦截。

排查步骤:检查代码里是否在循环里重复调用验证、或验证成功后还在反复请求。

解决办法:验证结果做本地缓存,成功后按心跳节奏(≥50 秒,建议 55 秒)再请求;不要在启动循环、窗口重绘等高频位置直接调接口。

8. system_locked 系统锁定

触发原因:你在后台关闭了验证开关(CARD_OFF),或平台系统维护中(system_locked 状态)。

排查步骤:登录后台查看验证开关状态。

解决办法:正常运营时保持开关打开;需要临时停服(如发新版前)可先关开关,客户端应把 system_locked 显示为「系统维护中,请稍后再试」而不是「卡密无效」。

四、带调试日志的完整对接代码

下面是 Python 版本的对接代码,内置了完整日志输出:每次请求打印 URL、返回原文、解析结果、错误码分支。对接期开着日志跑一遍,任何问题都能定位到具体环节。其他语言(易语言、C#、Java、Go 等)逻辑完全一致,照搬结构即可。

import time
import hashlib
import requests

# ===== 配置区(改成你自己的) =====
USERNAME = "你的用户名"        # 后台用户名
APP      = "你的应用名"        # 后台创建的应用名
SECRET   = "你的签名密钥"      # 后台 API 对接里的密钥
# ================================

def get_mac():
    """机器码采集:这里换成你项目的稳定机器码,如 CPU 序列号"""
    return "机器码"

def sign(data: str) -> str:
    """签名:MD5(业务数据 + 签名密钥),32 位小写"""
    return hashlib.md5((data + SECRET).encode("utf-8")).hexdigest()

def check(card: str, mac: str):
    t = str(int(time.time()))
    url = ("https://www.keyt.cn/kami/%s/check.php"
           "?card=%s&mac=%s&app=%s&heart=1&t=%s"
           % (USERNAME, card, mac, APP, t))
    print("[DEBUG] 请求地址:", url)

    resp = requests.get(url, timeout=10)
    raw = resp.text
    print("[DEBUG] 返回原文:", raw)

    if raw.startswith("error|"):
        code = raw.split("|")[1]
        print("[DEBUG] 错误码:", code)
        # 按错误码分支处理
        if code == "invalid_card":
            print("提示:卡密无效,请检查后重新输入")
        elif code == "expired":
            print("提示:卡密已过期,请续费")
        elif code == "device_mismatch":
            print("提示:设备不匹配,请联系客服解绑")
        elif code == "online_limit_reached":
            print("提示:在线设备数已达上限")
        elif code == "system_locked":
            print("提示:系统维护中,请稍后再试")
        else:
            print("提示:验证失败(%s)" % code)
        return False

    # 正常返回:业务数据|sign=xxx
    biz, _, sign_str = raw.rpartition("|")
    expect = "sign=" + sign(biz)
    print("[DEBUG] 本地签名:", expect)
    if sign_str != expect:
        print("[DEBUG] 签名不一致!检查密钥或业务数据拼接")
        return False
    print("[DEBUG] 业务数据:", biz)
    return True

if __name__ == "__main__":
    # 验证成功后按 55 秒心跳循环保活
    ok = check("你的卡密", get_mac())
    while ok:
        time.sleep(55)
        ok = check("你的卡密", get_mac())
💡
对接调试阶段把 print("[DEBUG] ...") 全保留;上线前可以去掉或改成写日志文件。代码里所有占位符(用户名/应用名/签名密钥/卡密)都要替换成真实值。

五、分步排查流程(对号入座)

  1. 浏览器直接打开拼接好的完整 URL——能返回正常数据,说明参数和地址没问题,问题在代码;返回错误码,进第 3 步。
  2. 代码里把返回原文完整打印,确认是否走到 error| 分支,还是解析/签名环节就挂了。
  3. 有错误码:对照第三节速查表定位,90% 是卡密状态或设备绑定问题。
  4. 没有错误码:回到第二节四个坑,重点查签名拼接和时间戳。
  5. 还不行:把「请求 URL + 返回原文 + 本地签名」三段日志发给卡密通客服(QQ:345205377),一分钟内就能定位。