API REFERENCE

Errors

Every error response has the same shape. The code field is stable across versions; the message is human-readable and may change. Always handle on code.

Response shape

{
  "error": "invalid_credentials",
  "code": "invalid_credentials",
  "message": "The supplied bearer token is malformed or expired.",
  "request_id": "req_xK2mP9nL3jH"
}

Code reference

HTTP	Code	Meaning	Action
400	`invalid_request`	Required field missing or malformed	Fix payload, retry
401	`invalid_credentials`	Bearer token missing or malformed	Re-fetch key from dashboard
403	`key_expired`	API key past expiration	Rotate key, retry
403	`tenant_disabled`	Tenant suspended (billing or ToS)	Contact billing
404	`user_not_enrolled`	No embedding for this user_id	Run /enroll first
409	`duplicate_request`	Idempotency key already processed	Use prior response
409	`already_enrolled`	user_id already has an embedding	Run /delete then /enroll
422	`low_confidence`	Verify completed but score < threshold	Surface for review or block
422	`liveness_failed`	Anti-spoof scorer triggered block	User retries; escalate to active liveness
422	`no_face_detected`	Supplied frames missing a face	Retry with new frames
422	`multiple_faces_detected`	One or more frames has > 1 face	Retry with single-face frames
429	`rate_limited`	Per-key or per-tenant cap exceeded	Retry with backoff (Retry-After header set)
500	`internal_error`	Lorica-side fault — auto-paged	Retry with backoff; check status page
503	`maintenance`	Scheduled maintenance window	Retry per Retry-After

Idempotency

Pass X-Lorica-Idempotency-Key on any POST to enable safe retries. If the same key is replayed within 24 hours, the original response is returned (verbatim, including the same JWT). Recommended for any retry-on-error path. Idempotency keys must be unique per logical request — using one across two distinct verifies will return the first one's verdict for both, which is almost certainly not what you want.

Tip

Treat 422 low_confidence as a soft fail, not a hard error. The verify call completed; the score just fell below your threshold. For some action classes (small trades, reads) you may accept a lower threshold than for others (whale withdrawals, beneficiary changes).