接口参考
错误码
全部错误码的含义、分类与是否可重试,以及出现在 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_EMPTY | source.items 是空的 | 否 |
SOURCE_TOO_MANY_ITEMS | 内容项超上限(最多 50 项,其中网页最多 10 项) | 否 |
DOCUMENT_INVALID | 模板文档未通过校验 | 否 |
DOCUMENT_SCHEMA_UNSUPPORTED | 文档 schema 版本不受支持 | 否 |
PDF_INVALID | PDF 无效或无法解析 | 否 |
IMAGE_DECODE_FAILED | 图片无法解码 | 否 |
HTML_INVALID | HTML 素材无效或类型 / 大小不符 | 否 |
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_UNAVAILABLE | Windows 打印后台服务不可用 | 是 |
WINDOWS_PRINTER_ACCESS_DENIED | Windows 拒绝访问该打印机 | 否 |
| 错误码 | 含义 | 可重试 |
|---|
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[] 里,任务仍然成功完成。应当展示给用户,
不要当失败处理。
| 码 | 含义 |
|---|
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 模板 |