Accelerator 오류

범위

이 다섯 가지 예외는 선택적인 Spectrum(Prism) 하드웨어 가속기 사이드카에서 발생하는 실패를 표면화합니다. 사이드카는 NextPDF\Accelerator\SpectrumClient를 통해 HTTP로 접근합니다. 오류 응답은 표준 분류 체계에서 정의된 기계 판독 가능 SPEC-* 코드를 담으며, 클라이언트는 그 코드를 아래 예외 타입 중 하나로 매핑합니다.

대부분의 NextPDF 예외와 달리, Accelerator 예외는 getContext()를 구현하지 않습니다. 이들은 PHP의 RuntimeException을 확장하고 상태를 타입이 지정된 readonly public 속성으로 노출합니다. 오류 영역은 서브클래스를 잡는 방식이 아니라 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-* 코드에 대해 발생하며, 라이선스, 토큰 또는 배포 바인딩 실패를 나타냅니다. SpectrumResponseParser는 응답 코드가 SPEC-AUTH-로 시작할 때마다 이를 발생시킵니다.

문서화된 원인에는 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으로 둡니다.

복구. 이 오류들은 운영자 개입 없이는 절대 재시도할 수 없습니다. 라이선스를 갱신하거나 바로잡고, Bearer 토큰을 새로 발급하거나, 배포 슬롯을 정렬한 뒤 호출을 다시 실행하십시오.

SpectrumResourceException

GPU 또는 CPU 메모리가 소진되었을 때 SPEC-OOM-* 코드에 대해 발생합니다. SpectrumResponseParser는 모든 SPEC-OOM- 접두사에 대해 이를 발생시키며, DegradePolicy::FailFast 설정은 낮은 하드웨어 등급으로 조용히 다운그레이드하는 대신 이를 발생시킵니다.

생성자는 retryable을 true로 고정하고 httpStatus를 기본값 503으로 둡니다.

복구. 이 예외는 재시도 가능합니다. 작업을 큐에 넣고 다른 작업이 완료되어 리소스가 해제된 뒤 재시도하거나, 다운그레이드된 등급이 해당 작업에 허용된다면 DegradePolicy를 AllowWithLog / WarnAndProceed로 완화하십시오.

SpectrumProtocolException

사이드카 응답이 JSON으로 파싱되지만 예상한 프로토콜 형태와 일치하지 않을 때 발생합니다. 항상 specCode SPEC-IO-003과 httpStatus 502를 사용하며, retryable은 false로 고정됩니다.

이는 SPEC-IO-001(잘못된 JSON)과 구분됩니다. 여기서는 JSON이 올바른 형식이지만 구조적으로 잘못되었으며, 일반적으로 프록시나 게이트웨이가 본문을 다시 쓰거나, 호환되지 않는 사이드카 버전이거나, 손상된 응답을 나타냅니다.

복구. 재시도할 수 없습니다. 응답 형태는 주어진 사이드카 버전에 대해 결정적입니다. 사이드카 버전을 클라이언트의 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이 필수일 때는 사이드카가 가동되어 접근 가능한지 확인한 뒤 호출을 다시 실행하십시오.

함께 보기

• 오류 참조 색인
• 암호화 및 권한
• 지식 베이스 색인