Error Reference
Error Reference
Every error the FaceVault API can return, with causes and resolution steps.
All errors are returned as JSON with a detail field:
{ "detail": "Human-readable error message" }Authentication Errors (401)
| Error | Cause | Resolution |
|---|---|---|
Authentication required | No auth header provided | Add X-FaceVault-Api-Key or X-Telegram-Init-Data header |
Invalid API key | API key not found or deactivated | Check the key is correct and the account is active |
Invalid Telegram initData | HMAC signature verification failed | Ensure initData is from a valid Telegram Mini App session and the bot token matches |
Cannot extract user from initData | initData is valid but contains no user object | The Telegram WebApp must be opened by a user (not a channel/group without user context) |
Authorization Errors (403)
| Error | Cause | Resolution |
|---|---|---|
Session belongs to another user | The authenticated user did not create this session | Each session is scoped to the user/API client that created it. Use the correct credentials. |
Not Found Errors (404)
| Error | Cause | Resolution |
|---|---|---|
Session not found | No session exists with this ID | Check the session_id is correct. Sessions are identified by a 32-character hex string. |
Validation Errors (400)
| Error | Cause | Resolution |
|---|---|---|
Invalid step. Must be 'id' or 'straight'. | The step form field is wrong | Use step=id for the ID document and step=straight for the selfie |
Session is not active | Session already completed or analyzing | Create a new session. A session can only be completed once. |
Empty file | Uploaded file has zero bytes | Ensure the photo file is not empty |
Invalid file path | Path traversal attempt detected | Use a valid session ID |
Required photos not yet uploaded | Called /complete before both photos uploaded | Upload both id and straight photos before completing |
Photo Validation Errors
Returned with HTTP 200 but valid: false in the response body. The user should retake the photo.
| Error | Step | Cause | Resolution |
|---|---|---|---|
Could not read image. Please try again. | Both | File is corrupted or not a valid image | Upload a valid JPEG photo |
Image is too dark. Please ensure good lighting. | Both | Average brightness below threshold | Retake in better lighting |
Image appears blank. Please position your ID in the frame. | Both | Near-zero contrast (solid colour) | Ensure the document or face is in frame |
No face detected. Please look directly at the camera. | Selfie | MediaPipe found no face | Face the camera directly with good lighting |
Face Analysis Errors
Returned from /complete with HTTP 200 and passed: false when the ML pipeline completes but verification fails.
| Error | Cause | Resolution |
|---|---|---|
Face match failed. | Face on ID does not match the selfie | Ensure both photos are of the same person with the face clearly visible |
No face found in ID photo | ArcFace could not detect a face on the document | Re-upload a clearer ID photo with the face visible |
No face found in selfie | ArcFace could not detect a face in the selfie | Re-upload a clearer selfie looking directly at the camera |
Server Errors (500)
| Error | Cause | Resolution |
|---|---|---|
Server misconfigured | Bot token not set (Telegram auth only) | Server-side configuration issue. Contact support@facevault.id. |
HTTP Status Code Summary
| Code | Meaning |
|---|---|
| 200 | Success (check valid or passed field for result) |
| 201 | Session created |
| 400 | Bad request (invalid input, wrong state) |
| 401 | Authentication failed |
| 403 | Not authorized for this resource |
| 404 | Resource not found |
| 422 | Request body validation failed (missing/malformed JSON fields) |
| 500 | Internal server error |
More resources
Quickstart guide — zero to first API call in 5 minutes
Interactive API explorer — Swagger UI with all endpoints
Download Postman collection — import and start testing immediately