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
{
"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
| Code | HTTP | Retryable | Meaning & Recommended Action |
|---|---|---|---|
| NO_FACE | 422 | true | No detectable face found in the frame. Ask the user to center their face in the frame and retry. |
| MULTIPLE_FACES | 422 | true | More than one face detected where a single subject is required. Prompt the user to capture alone without bystanders. |
| FACE_TOO_SMALL | 422 | true | Interocular pixel distance is below the minimum threshold. Move the camera closer to the subject. |
| BAD_IMAGE | 400 | false | Payload could not be decoded as a supported image. Verify JPEG/PNG/WebP encoding before uploading. |
| UNSUPPORTED_MEDIA | 415 | false | Content type is not an accepted image format. Send image/jpeg, image/png, or image/webp. |
| SIZE_LIMIT | 413 | false | Uploaded file exceeds configured maximum payload size. Compress or downscale image prior to upload. |
| LOW_QUALITY | 422 | true | Combined quality score fell below policy q_min (40.0). Inspect reasons[] and prompt recapture. |
| LOW_LIGHT | 422 | true | Frame illumination is too dark for reliable embedding. Prompt user to face a light source. |
| OCCLUDED | 422 | true | Critical facial landmarks are obscured by mask, hand, or glare. Ask user to remove obstructions. |
| QUALITY_RECAPTURE | 422 | true | Screen moiré or recapture artifacts detected in quality gate. Reject photo-of-screen and request live camera capture. |
| UNAUTHORIZED | 401 | false | Missing, malformed, or revoked Bearer API key. Check Authorization header and active key status. |
| FORBIDDEN | 403 | false | Key lacks required scope or cross-tenant resource access attempted. Verify key scopes and tenant ownership. |
| CONSENT_REQUIRED | 422 | false | Enrollment attempted without a valid, active consent_id. Create a consent via POST /v1/consents first. |
| ENROLLMENT_REVOKED | 403 | false | Consent for the referenced subject was withdrawn. Re-collect consent and re-enroll before verifying. |
| RATE_LIMITED | 429 | true | Tenant request rate or concurrency limit exceeded. Back off exponentially using Retry-After. |
| IDEMPOTENCY_CONFLICT | 409 | false | Idempotency-Key reused with a different request payload. Generate a fresh UUID per distinct operation. |
| MODEL_VERSION_MISMATCH | 409 | false | Stored template model version differs from active embedder. Re-enroll template or pin compatible model version. |
| MODEL_NOT_APPROVED | 503 | false | Active model failed commercial licensing gate. Verify registry manifest and license compliance. |
| MODEL_UNAVAILABLE | 503 | true | Inference runtime could not execute the required model. Retry safely; engine never defaults to MATCH. |
| CALIBRATION_MISSING | 503 | false | No calibrated threshold exists for the requested model and profile. Run calibration CLI or select an active profile. |
| PAD_FAILED | 403 | false | Presentation attack detected (print, replay, or mask). Treat as REJECT and block or escalate session. |
| PAD_INCONCLUSIVE | 422 | true | Liveness score fell inside the uncertain band. Escalate to active or multi-view challenge. |
| SESSION_EXPIRED | 422 | true | Liveness session exceeded its TTL window. Mint a new session via POST /v1/liveness/sessions. |
| SESSION_REPLAYED | 403 | false | Attempted reuse of an already-consumed one-time liveness session. Reject attempt and create a fresh session. |
| INVALID_SIGNATURE | 403 | false | HMAC-SHA256 capture manifest signature failed verification. Ensure client signs exact nonce, timestamps, and SHA-256 frame hashes. |
| INSUFFICIENT_VIEWS | 422 | true | Fewer than 3 views supplied for multi-view 3D check. Capture left, centre, and right angles. |
| VIEW_DISAGREEMENT | 422 | true | 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.
| Reason | Stage | Cause & Suggested User Prompt |
|---|---|---|
| BLURRY | Quality | Motion or focus blur degraded facial texture. UI prompt: “Hold the camera steady and tap to focus.” |
| TOO_DARK | Quality | Insufficient ambient light on the face. UI prompt: “Move to a brighter area or face a window.” |
| OVEREXPOSED | Quality | Strong backlight or flash washed out facial features. UI prompt: “Avoid direct glare behind or in front of you.” |
| POSE_TOO_LARGE | Quality | Head yaw, pitch, or roll exceeded calibration envelope. UI prompt: “Look straight into the camera.” |
| FACE_TOO_SMALL | Quality | Face occupies too few pixels for reliable matching. UI prompt: “Bring the camera closer to your face.” |
| OCCLUDED | Quality | Sunglasses, mask, or hand covers key landmarks. UI prompt: “Remove glasses or obstructions from your face.” |
| EYES_CLOSED | Quality | Subject blinked or kept eyes shut during capture. UI prompt: “Keep both eyes open during capture.” |
| SPOOF_SUSPECTED | Liveness | Passive or active PAD flagged presentation attack cues. UI prompt: “Use a real live camera feed without screens or printouts.” |
| POSE_NOT_PROGRESSIVE | Multi-View | Left -> centre -> right views did not follow natural yaw progression. UI prompt: “Turn your head smoothly left, then centre, then right.” |
| SHAPE_INCONSISTENT | Multi-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_DRIFT | Multi-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_SIMILARITY | Matching | Score landed near the decision boundary or margin gap in 1:N search. UI prompt: “Retry with clearer lighting or stricter active liveness.” |