For the complete documentation index, see llms.txt

Proof server errors

증명 서버는 트랜잭션에 대한 영지식 증명을 생성하는 독립형 HTTP 서비스입니다. midnight-ledger 저장소의 일부이며 일반적으로 6300 포트에서 실행됩니다.

midnight-ledger에서 오류 처리에 thiserror derive를 사용하는 유일한 크레이트입니다. 서버는 오류를 HTTP 상태 코드에 매핑하여 HTTP 응답으로 반환합니다.

Worker pool errors (`WorkerPoolError`)

증명 서버의 내부 작업 큐 및 워커 풀 관리에서 발생하는 오류입니다.

HTTP status	Error	Description	Fix
400 Bad Request	`JobNotPending(Uuid)`	대기 상태가 아닌 작업을 취소하려는 경우	해당 작업은 이미 처리 중이거나, 완료됐거나, 취소된 상태입니다
428 Precondition Required	`JobMissing(Uuid)`	참조한 작업을 찾을 수 없는 경우	작업 ID가 유효하지 않거나 만료된 경우입니다
429 Too Many Requests	`JobQueueFull`	증명 생성 작업 큐가 가득 찬 경우	잠시 기다렸다가 재시도하세요. 서버 부하가 높은 상태입니다
500 Internal Server Error	`ChannelClosed`	내부 작업 채널이 닫힌 경우	증명 서버를 재시작하세요

실제 증명 생성 과정에서 발생하는 오류입니다.

HTTP Status	Error	Description	Fix
400 Bad Request	`BadInput(String)`	증명 요청 입력 데이터가 유효하지 않은 경우	증명을 위해 전송한 트랜잭션 데이터를 확인하세요
500 Internal Server Error	`CancelledUnexpectedly`	명시적 요청 없이 시스템이 작업을 취소한 경우	내부 오류입니다. 증명 요청을 재시도하세요
500 Internal Server Error	`InternalError(String)`	내부 증명 생성 오류	증명 서버 로그를 확인하세요. 오류가 계속되면 증명 서버를 재시작하세요
500 Internal Server Error	`JoinError`	증명 생성 중 태스크 join 오류	내부 스레딩 오류입니다. 재시도하거나 재시작하세요

증명 서버는 각 증명 작업을 다음 상태로 추적합니다.

/ready 엔드포인트로 증명 서버가 새 요청을 받을 수 있는지 확인하세요.

Endpoint	HTTP status	Description
`GET /ready`	200 OK	서버가 증명 요청을 받을 준비가 된 상태
`GET /ready`	503 Service Unavailable	서버가 사용 중인 상태 (모든 워커 점유)

가장 자주 발생하는 문제와 그 원인을 다음 표에 정리했습니다.

Symptom	Likely cause	Fix
429 응답	너무 많은 증명 요청이 서버로 동시에 전송되는 경우	병렬 증명 요청 수를 줄이고, 부하 상황에서 요청 간격을 두도록 지수 백오프 재시도 전략을 구현하세요
`/ready`의 503 응답	모든 증명 워커가 사용 중인 경우	진행 중인 증명이 완료될 때까지 기다리거나 설정에서 워커 수를 늘리세요
"BadInput"이 포함된 500 응답	트랜잭션 데이터 형식이 잘못된 경우	SDK로 트랜잭션을 올바르게 빌드했는지 확인하세요
6300 포트 연결 거부	증명 서버가 실행 중이지 않은 경우	증명 서버 컨테이너를 시작하고 Docker 상태를 확인하세요
느린 증명 생성	회로가 크거나 리소스가 부족한 경우	증명 서버 컨테이너에 CPU나 메모리를 더 할당하세요