F

Reference

Error & Reason Codes

Every error response carries a canonical code, HTTP status, retryable flag, and request_id. Decision responses also surface non-fatal reason codes so you can guide users to recapture.

Standard Error Envelope

ErrorDetailResponse
{
  "request_id": "req_01j9m2x9k6",
  "code": "LOW_QUALITY",
  "message": "Probe image failed quality gate (score=27.5 < q_min=40.0).",
  "retryable": true,
  "reasons": ["BLURRY", "TOO_DARK"],
  "details": { "score": 27.5, "q_min": 40.0 }
}

HTTP & Application Error Codes

CodeHTTPRetryableMeaning & Recommended Action
NO_FACE422true

No detectable face found in the frame.

Ask the user to center their face in the frame and retry.

MULTIPLE_FACES422true

More than one face detected where a single subject is required.

Prompt the user to capture alone without bystanders.

FACE_TOO_SMALL422true

Interocular pixel distance is below the minimum threshold.

Move the camera closer to the subject.

BAD_IMAGE400false

Payload could not be decoded as a supported image.

Verify JPEG/PNG/WebP encoding before uploading.

UNSUPPORTED_MEDIA415false

Content type is not an accepted image format.

Send image/jpeg, image/png, or image/webp.

SIZE_LIMIT413false

Uploaded file exceeds configured maximum payload size.

Compress or downscale image prior to upload.

LOW_QUALITY422true

Combined quality score fell below policy q_min (40.0).

Inspect reasons[] and prompt recapture.

LOW_LIGHT422true

Frame illumination is too dark for reliable embedding.

Prompt user to face a light source.

OCCLUDED422true

Critical facial landmarks are obscured by mask, hand, or glare.

Ask user to remove obstructions.

QUALITY_RECAPTURE422true

Screen moiré or recapture artifacts detected in quality gate.

Reject photo-of-screen and request live camera capture.

UNAUTHORIZED401false

Missing, malformed, or revoked Bearer API key.

Check Authorization header and active key status.

FORBIDDEN403false

Key lacks required scope or cross-tenant resource access attempted.

Verify key scopes and tenant ownership.

CONSENT_REQUIRED422false

Enrollment attempted without a valid, active consent_id.

Create a consent via POST /v1/consents first.

ENROLLMENT_REVOKED403false

Consent for the referenced subject was withdrawn.

Re-collect consent and re-enroll before verifying.

RATE_LIMITED429true

Tenant request rate or concurrency limit exceeded.

Back off exponentially using Retry-After.

IDEMPOTENCY_CONFLICT409false

Idempotency-Key reused with a different request payload.

Generate a fresh UUID per distinct operation.

MODEL_VERSION_MISMATCH409false

Stored template model version differs from active embedder.

Re-enroll template or pin compatible model version.

MODEL_NOT_APPROVED503false

Active model failed commercial licensing gate.

Verify registry manifest and license compliance.

MODEL_UNAVAILABLE503true

Inference runtime could not execute the required model.

Retry safely; engine never defaults to MATCH.

CALIBRATION_MISSING503false

No calibrated threshold exists for the requested model and profile.

Run calibration CLI or select an active profile.

PAD_FAILED403false

Presentation attack detected (print, replay, or mask).

Treat as REJECT and block or escalate session.

PAD_INCONCLUSIVE422true

Liveness score fell inside the uncertain band.

Escalate to active or multi-view challenge.

SESSION_EXPIRED422true

Liveness session exceeded its TTL window.

Mint a new session via POST /v1/liveness/sessions.

SESSION_REPLAYED403false

Attempted reuse of an already-consumed one-time liveness session.

Reject attempt and create a fresh session.

INVALID_SIGNATURE403false

HMAC-SHA256 capture manifest signature failed verification.

Ensure client signs exact nonce, timestamps, and SHA-256 frame hashes.

INSUFFICIENT_VIEWS422true

Fewer than 3 views supplied for multi-view 3D check.

Capture left, centre, and right angles.

VIEW_DISAGREEMENT422true

Views fail progressive yaw, 3D shape, or cross-view identity checks.

Re-run multi-view capture smoothly turning head left to right.

Decision Reason Codes

Returned inside reasons[] on verification, quality, liveness, and multi-view responses so your UI can show clear recapture guidance.

ReasonStageCause & Suggested User Prompt
BLURRYQuality

Motion or focus blur degraded facial texture.

UI prompt: “Hold the camera steady and tap to focus.”

TOO_DARKQuality

Insufficient ambient light on the face.

UI prompt: “Move to a brighter area or face a window.”

OVEREXPOSEDQuality

Strong backlight or flash washed out facial features.

UI prompt: “Avoid direct glare behind or in front of you.”

POSE_TOO_LARGEQuality

Head yaw, pitch, or roll exceeded calibration envelope.

UI prompt: “Look straight into the camera.”

FACE_TOO_SMALLQuality

Face occupies too few pixels for reliable matching.

UI prompt: “Bring the camera closer to your face.”

OCCLUDEDQuality

Sunglasses, mask, or hand covers key landmarks.

UI prompt: “Remove glasses or obstructions from your face.”

EYES_CLOSEDQuality

Subject blinked or kept eyes shut during capture.

UI prompt: “Keep both eyes open during capture.”

SPOOF_SUSPECTEDLiveness

Passive or active PAD flagged presentation attack cues.

UI prompt: “Use a real live camera feed without screens or printouts.”

POSE_NOT_PROGRESSIVEMulti-View

Left -> centre -> right views did not follow natural yaw progression.

UI prompt: “Turn your head smoothly left, then centre, then right.”

SHAPE_INCONSISTENTMulti-View

2D projective deformation matched a flat plane rather than a 3D head.

UI prompt: “Do not tilt a photo; capture a real person turning.”

IDENTITY_DRIFTMulti-View

Embeddings across multi-view frames did not belong to the same person.

UI prompt: “Keep the same person centered through all three angles.”

BORDERLINE_SIMILARITYMatching

Score landed near the decision boundary or margin gap in 1:N search.

UI prompt: “Retry with clearer lighting or stricter active liveness.”