Error codes

Every failure from the iLive API carries a short, stable machine-readable code alongside the human-readable message. Match on code in your error handlers; treat message as advisory text that may change.

Response envelope

All errors share the same shape:

{
  "detail": {
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key"
  }
}

The detail wrapper is FastAPI's convention and is consistent across v1 and v2. The HTTP status code carries the category; the code disambiguates within the category.

Codes

Authentication and rate limiting

Code	HTTP	Surface	When it fires	How to fix
`missing_api_key`	401	Auth	No `Authorization` header present.	Add `Authorization: Bearer iksk_...`.
`invalid_api_key`	401	Auth	Key unknown or revoked.	Re-issue a key via portal / support.
`account_inactive`	403	Auth	The owning account is suspended.	Contact your account manager.
`rate_limited`	429	Auth	Per-key RPM or RPS limit exceeded.	Back off with jitter; see Rate limits.

Face Services — detect, compare

Code	HTTP	Surface	When it fires	How to fix
`image_too_large`	413	Face Services	Upload larger than 8 MB.	Downscale or recompress before sending.
`empty_image`	400	Face Services	Request body image field is empty.	Ensure the file part is populated.
`invalid_image`	400	Face Services	Bytes cannot be decoded as an image.	Confirm the file is a valid JPEG / PNG.
`invalid_attributes`	400	Face Services	`attributes` param not one of `default`, `all`, `none`.	Use one of the three supported values.
`no_face_in_source`	422	Face Services (compare)	No face found in the source image.	Provide a clearer, front-facing source.
`no_face_in_target`	422	Face Services (compare)	No face found in the target image.	Provide a clearer, front-facing target.

Collections and indexed faces

Code	HTTP	Surface	When it fires	How to fix
`collection_exists`	409	Collections	`POST /collections` with an `external_id` that already exists.	Choose a new ID or reuse the existing collection.
`collection_not_found`	404	Collections	Referenced collection does not exist.	Create it first, or fix a typo in the path.
`invalid_quality_filter`	400	Index	`quality_filter` not one of `none`, `low`, `medium`, `high`.	Use a supported value.
`invalid_face_id`	400	Index	Path `face_id` is not a UUID.	Pass a valid UUID returned by a prior index call.
`invalid_face_ids`	400	Index	One or more `face_ids` in a batch body are not UUIDs.	Validate every ID before submitting.
`face_not_found`	404	Index	Face with that UUID is not in the collection.	Verify the ID and the collection.

Images sent to the index and search endpoints are subject to the same image_too_large (413) and empty_image (400) checks as detect and compare.

Not sure which code you're seeing?

Every customer-facing error is emitted by one of these routers — check the surface column above and the corresponding reference page: