error codes API

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

Updated: 2026-05-19 12:49:24

Version History¶

Version	Date	Changes
1.0	2026-10-24	Initial documentation