接口参考

错误码

全部错误码的含义、分类与是否可重试,以及出现在 warnings 里的非错误码。

最后更新

每个失败都是结构化错误:code(稳定的机器码,跨版本不变)、message (技术性描述)、retryable(原样重试是否有意义),可能还有 details。

怎么用

  • 按 code 分支,不要解析 message 文本——它会随版本调整。
  • retryable 为「是」的错误,原样重试通常能成功(等用户确认、限流窗口结束…); 为「否」的错误需要先改参数或环境。
  • 机器可读目录可以从 @printlink/types 导入:ERROR_CATALOG 与 errorCatalogEntry(code),与本页始终一致。
import { PrintLinkClient, PrintLinkError, TransportError } from '@printlink/sdk';

try {
  await client.connect();
  await client.ensureAuthorized();
} catch (err) {
  if (err instanceof PrintLinkError) {
    switch (err.code) {
      case 'PAIRING_PENDING':   // 正常状态:提示用户去电脑上同意,然后重试
        break;
      case 'PAIRING_DENIED':    // 用户拒绝:说明原因并提供重新申请入口
        break;
      case 'PERMISSION_DENIED': // 缺权限:引导用户补权限
        break;
      default:
        console.warn(err.code, err.message, 'retryable =', err.retryable);
    }
  } else if (err instanceof TransportError) {
    // 连接层:没启动 / 端口不对 / 连接被拒 —— 引导安装或检查端口
  } else {
    throw err;
  }
}

授权与连接

错误码含义可重试
PAIRING_REQUIRED尚未完成配对授权否
PAIRING_PENDING已请求权限,等本机用户确认(不是故障)是
PAIRING_DENIED配对请求被拒绝否
PERMISSION_DENIED超出已授予的权限范围否
TOKEN_INVALID令牌无效或已被撤销否
ORIGIN_NOT_ALLOWED该来源未被允许访问否
ORIGIN_CATEGORY_DENIED该来源类型始终不允许(如 file:)否
REMOTE_SOURCE_DENIED来源设备未满足网络白名单否
REMOTE_NATIVE_CLIENT_DENIED远程非浏览器程序未带 Origin,被拒绝否
PROTOCOL_MISMATCH客户端与 PrintLink 协议版本不匹配否
RATE_LIMITED调用过于频繁,被临时限流是
AGENT_SHUTTING_DOWN服务正在关闭,暂不接收新任务是

打印机与配置档

错误码含义可重试
PRINTER_NOT_FOUND打印机不存在或已被移除否
PRINTER_OFFLINE打印机离线,任务未提交到队列否
PRINTER_BUSY打印机正忙是
CAPABILITIES_UNAVAILABLE暂时读不到打印机能力是
NATIVE_SETTINGS_UNAVAILABLE当前平台无法打开原生设置否
PROFILE_INVALID配置档已不匹配当前打印机或驱动否
PROFILE_NOT_FOUND配置档不存在否
PROFILE_PRINTER_MISMATCH配置档与目标打印机不匹配否

打印参数

错误码含义可重试
UNSUPPORTED_PRINT_OPTION参数超出打印机能力否
INVALID_PAPER_SIZE纸张尺寸无效或超范围否
COLOR_NOT_SUPPORTED不支持彩色否
DUPLEX_NOT_SUPPORTED不支持双面否
TRAY_NOT_SUPPORTED指定纸盒不可用否
RESOLUTION_NOT_SUPPORTED指定的分辨率不支持否
WINDOWS_DEVMODE_REJECTED驱动拒绝了该参数组合否

内容

错误码含义可重试
SOURCE_EMPTYsource.items 是空的否
SOURCE_TOO_MANY_ITEMS内容项超上限(最多 50 项,其中网页最多 10 项)否
DOCUMENT_INVALID模板文档未通过校验否
DOCUMENT_SCHEMA_UNSUPPORTED文档 schema 版本不受支持否
PDF_INVALIDPDF 无效或无法解析否
IMAGE_DECODE_FAILED图片无法解码否
HTML_INVALIDHTML 素材无效或类型 / 大小不符否
HTML_SNAPSHOT_UNAVAILABLE当前环境无法生成网页快照否
HTML_SNAPSHOT_TIMEOUT网页快照超时否
HTML_SNAPSHOT_TOO_MANY_PAGES单个网页项超过 50 页否
FONT_NOT_FOUND引用的字体不可用否
RENDER_FAILED渲染最终成品失败否
ASSET_NOT_FOUND / ASSET_HASH_MISMATCH素材不存在 / 哈希不一致否
UPLOAD_INVALID上传请求无效或超限否
PAYLOAD_TOO_LARGE请求体超限否
CONTENT_EXPIRED / CONTENT_NOT_RETAINED内容已过期 / 未保留否
PREVIEW_NOT_FOUND / PREVIEW_UNAVAILABLE预览会话不存在 / 暂时不可用否

任务

错误码含义可重试
JOB_NOT_FOUND任务不存在否
JOB_CANNOT_CANCEL当前状态不允许取消否
SPOOL_SUBMIT_FAILED提交到系统打印队列失败否
PRINT_FAILED打印执行失败否
QUEUE_FULL任务队列已满是
AGENT_STOPPED_BEFORE_FINISH服务在任务完成前停止了否
OS_SHUTDOWN_TIMEOUT系统关机等待超时否
WINDOWS_SPOOLER_UNAVAILABLEWindows 打印后台服务不可用是
WINDOWS_PRINTER_ACCESS_DENIEDWindows 拒绝访问该打印机否

扫描

错误码含义可重试
SCANNER_NOT_FOUND / SCANNER_OFFLINE扫描仪不存在 / 离线否
SCANNER_BUSY设备或该站点已有进行中的扫描是
SCANNER_CAPABILITIES_UNAVAILABLE设备未返回能力描述是
SCANNER_BACKEND_UNAVAILABLE当前进程没有可用的扫描后端否
UNSUPPORTED_SCAN_OPTION参数超出设备能力否
SCAN_DISABLED设置里关闭了扫描否
SCAN_CONSENT_DENIED用户拒绝了这次扫描否
SCAN_CONSENT_TIMEOUT桌面确认超时,作业已取消是
SCAN_SOURCE_EMPTY进纸器无纸是
SCAN_DEVICE_ERROR设备扫描中报错(卡纸、盖板打开)否
SCAN_TRANSFER_FAILED成品传输失败是
SCAN_TOO_LARGE / SCAN_TIMEOUT页数 / 体积 / 时长超限否 / 是
SCAN_NOT_FOUND作业不存在或不属于当前站点否
SCAN_CANNOT_CANCEL已进入终态,无法取消否

系统与设备

错误码含义可重试
INVALID_REQUEST请求格式无效否
METHOD_NOT_FOUND方法不存在否
UNSUPPORTED当前平台或版本不支持否
INTERNAL内部错误是
PORT_UNAVAILABLE新端口无法绑定(旧服务仍可用)否
PORT_MIGRATION_FAILED监听配置迁移失败,已回滚否
LISTEN_SCOPE_BIND_FAILED所选范围内的地址无法绑定否
UNSAFE_CONFIG_REJECTED配置违反安全底线,被拒绝否
POLICY_LOCKED / POLICY_INVALID设置被机器策略锁定 / 策略文件无效否
DEVICE_NOT_FOUND / DEVICE_PAYLOAD_INVALID原始设备不存在 / 载荷校验失败否
DEVICE_TRANSPORT_FAILED设备传输失败是
DEVICE_PROTOCOL_UNSUPPORTED设备协议不受支持否
CONTENT_UNSUPPORTED / CONTENT_OPEN_FAILED内容无法安全展示 / 打开失败否

远程素材的两个错误

远程抓取失败时是 REMOTE_FETCH_DENIED(目标不是公网地址或不满足限制)或 REMOTE_FETCH_TOO_LARGE(响应体超限)。消息里只会出现来源类别, 不会回显地址或完整 URL。

warnings(不是错误)

这些码出现在成功返回值的 warnings[] 里,任务仍然成功完成。应当展示给用户, 不要当失败处理。

码含义
UNSUPPORTED_PRINT_OPTION该选项不被支持,已忽略或降级
OPTION_IGNORED该选项被驱动丢弃
PAGE_LAYOUT_EMULATED任务级 fill 由软件模拟实现
PAGE_RANGE_CLAMPED页段部分越界,已截到实际页数
MIXED_PAGE_SIZES_UNIFIED未给纸张且内容页尺寸不一致,已取最大页
PAPER_DEFAULTED未给纸张且推断不出,用了打印机默认
MEDIA_TYPE_UNVERIFIED打印机没报告纸张类型,无法确认取值有效
BINDING_MISSING模板占位符在数据里没有对应路径
BINDING_VALUE_INVALID图片绑定的取值不合法,已回退到静态图片
HTML_SNAPSHOT_UNAVAILABLE网页快照不可用(部分场景下作为警告)
HIPRINT_*Hiprint 转换过程中的降级,见 Hiprint 模板

相关页面

本页目录