← Back to index

Error Response Format

All API errors follow this JSON structure:

{
  "success": false,
  "error": {
    "code": "E001_NOT_FOUND",
    "message": "Resource not found",
    "details": {"resource": "file_uuid", "value": "abc"}
  }
}

Error Code List

Generic Errors (E0xx)

Code HTTP Description
E001_NOT_FOUND 404 Resource not found (file, identity, chunk)
E002_DUPLICATE 409 Resource already exists
E003_VALIDATION 400 Request parameter validation failed
E004_UNAUTHORIZED 401 Invalid API key or token
E005_INTERNAL 500 Internal server error

Processor Errors (E1xx)

Code HTTP Description
E101_PROCESSOR_FAIL 500 Python script execution failed
E102_TIMEOUT 504 Processing timeout
E103_RESUME_FAIL 500 Resume failed (checkpoint not found)
E104_NO_VIDEO 400 Video file path not found

Identity Errors (E2xx)

Code HTTP Description
E201_FACE_NOT_FOUND 404 Face detection not found
E202_MERGE_CONFLICT 409 Identity merge conflict
E203_CANDIDATE_EMPTY 404 No candidates available for confirmation

TMDb Errors (E3xx)

Code HTTP Description
E301_TMDB_NO_KEY 400 TMDB_API_KEY environment variable not set
E302_TMDB_UNREACHABLE 502 TMDb API unreachable or timed out
E303_TMDB_CACHE_NOT_FOUND 200 No local TMDb cache; run prefetch first
E304_TMDB_PROBE_FAILED 500 TMDb probe execution failed
E305_TMDB_MOVIE_NOT_FOUND 404 No matching TMDb movie found from filename