Accelerator 错误

范围

这五个异常会浮现来自可选 Spectrum（Prism） 硬件加速器边车的失败。该边车经由 HTTP 通过 NextPDF\Accelerator\SpectrumClient 触及；错误响应携带一个来自规范分类法的、机器可读的 SPEC-* 代码，而客户端会把该代码映射到下文的某个异常类型上。

与大多数 NextPDF 异常不同，Accelerator 异常不实现 getContext()。它们继承 PHP 的 RuntimeException，并把它们的状态暴露为类型化的 readonly 公开属性。请通过匹配 specCode 前缀（例如 str_starts_with($e->specCode, 'SPEC-AUTH-')）来区分错误域， 而非通过捕获子类——子类层级是内部的，可能会在次要版本中改变。

SpectrumApiException

SpectrumApiException 是每个边车错误响应的基类型。对于任何没有更具体子类的 SPEC-* 代码，它会被直接抛出，而它也是你用来一次性处理所有边车错误的类型。

何时抛出

• 边车返回一个结构化的 SPEC-* 错误体。SpectrumResponseParser 会解码该体，并为除 SPEC-AUTH-* 和 SPEC-OOM-*（它们映射到下文的子类）以外的所有代码抛出这个类型。映射到这个基类型的已记录映射包括 SPEC-INDEX-*（集合索引）、SPEC-KMS-*（密钥管理提供者）、SPEC-OCR-*、SPEC-MODEL-* 和 SPEC-BILLING-*。
• SPEC-IO-001 — 响应体不是有效的 JSON（httpStatus 502）。
• SPEC-IO-002 — 边车 API 版本与已配置的 minApiVersion 不兼容。
• SPEC-SEC-001 — 一个文档负载超出已配置的大小预算 （SpectrumSecurityPolicy::validatePayloadSize()）。
• SPEC-SEC-003 — 一个工作区路径未通过遍历检查 （SpectrumSecurityPolicy::validateWorkspacePath()）。
• SPEC-SEC-004 — 一个作业标识符为空、过长，或包含不透明 ID 允许列表之外的字符（SpectrumSecurityPolicy::validateJobId()）。

属性

属性	类型	含义
specCode	string	机器可读的 SPEC-* 错误代码（例如 SPEC-INDEX-003）。
httpStatus	int	边车返回的 HTTP 状态；默认为 500。也用作异常代码。
retryable	bool	该操作是否可被安全地重试。默认为 false。
traceId	?string	来自 X-Trace-Id 响应头的关联追踪 ID，或 null。

消息组合为 "[{specCode}] {message}"。三个辅助谓词对常见域进行分类：isKmsError()（SPEC-KMS-*）、isIndexError() （SPEC-INDEX-*），以及 isOcrError()（SPEC-OCR-*）。

恢复

1. 阅读 specCode 以识别失败的域；在其前缀上分支。
2. 尊重 retryable：仅当它为 true 时才重试，且绝不要在一个 SPEC-SEC-* 或 SPEC-IO-002 代码上重试，它们表示配置或兼容性缺陷。
3. 在你的日志中捕获 traceId，以便在一份缺陷报告中把该失败与边车端的诊断关联起来。

Spectrum 子类

以下类型是 SpectrumApiException 的 final 子类。请捕获 SpectrumApiException（或在 specCode 上匹配），而非直接捕获它们。

SpectrumAuthenticationException

为 SPEC-AUTH-* 代码抛出，表示一次许可证、令牌或部署绑定失败。每当响应代码以 SPEC-AUTH- 开头时， SpectrumResponseParser 就会抛出它。

已记录的原因包括 SPEC-AUTH-001（无效的许可证 Ed25519 签名）、 SPEC-AUTH-002（许可证过期且在宽限期之外）、SPEC-AUTH-003 （部署槽位不匹配）、SPEC-AUTH-004（无效的 JWT Bearer 令牌）、 SPEC-AUTH-006（许可证降级，宽限期过期），以及 SPEC-AUTH-007（所购许可证中不包含该特性）。

它携带与基类型相同的属性，但构造函数把 retryable 钉为 false，并把 httpStatus 默认为 403。

Recovery. 这些错误在没有运维介入的情况下绝不可重试。 续订或纠正许可证、刷新 Bearer 令牌，或对齐部署槽位，然后重新运行该调用。

SpectrumResourceException

当 GPU 或 CPU 内存被耗尽时，为 SPEC-OOM-* 代码抛出。 SpectrumResponseParser 会为任何 SPEC-OOM- 前缀抛出它，而 DegradePolicy::FailFast 设置会抛出它，而非静默地降级到一个更低的硬件层级。

构造函数把 retryable 钉为 true，并把 httpStatus 默认为 503。

Recovery. 这个异常是可重试的。把作业排队，并在其他作业完成并释放资源之后重试，或者如果一个降级层级对该工作负载可接受，则把 DegradePolicy 放宽到 AllowWithLog / WarnAndProceed。

SpectrumProtocolException

当一个边车响应解析为 JSON 但不匹配预期的协议形态时抛出。它始终使用 specCode SPEC-IO-003 和 httpStatus 502， 且 retryable 被钉为 false。

这与 SPEC-IO-001（无效的 JSON）不同：在此 JSON 是良构的， 但结构上是错误的，这通常表示一个代理或网关重写了该体、一个不兼容的边车版本，或一个损坏的响应。

Recovery. 不可重试——对于一个给定的边车版本，响应形态是确定性的。对照客户端的 minApiVersion 核实边车版本、 检查任何中间代理或网关，然后重新部署一个兼容的边车。

SpectrumNotAvailableException

SpectrumNotAvailableException 直接继承 RuntimeException，且不 是 SpectrumApiException 层级的一部分。它表示在任何 SPEC-* 错误体能够被返回之前，该边车不可达或未通过一次健康检查。

何时抛出

• 断路器打开，或所有重试尝试都已耗尽 （SpectrumClient）。
• 在联系边车时发生一次 HTTP 传输错误；底层的 PSR-18 ClientExceptionInterface 作为前一个异常被链接。
• 在边车报告其自身不可用时请求了一个 server-sent-events 流（SseStreamClient）。

属性

这个类型不携带任何 SPEC-* 元数据。消息组合为 "Spectrum sidecar unavailable: {reason}"，带有一个可选的整数 code 和一个链接的 previous throwable。

恢复

当 Spectrum 是可选的时捕获它，并回退到 PHP 原生处理 （优雅降级）。当 Spectrum 是必需的时，确认边车已启动且可达，然后重新运行该调用。

另请参阅

• Error reference index
• Encryption and permissions
• Knowledge base index