Error Codes Reference

All API errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

---

Authentication Errors

Code	HTTP Status	Description
MISSING_API_KEY	401	X-API-Key header is missing
INVALID_API_KEY	401	The provided API key is invalid or doesn't exist
ACCOUNT_DISABLED	403	Your business account has been disabled
MISSING_AUTH	401	Authorization header is missing (admin routes)
INVALID_TOKEN	401	Invalid admin token
NOT_AUTHENTICATED	401	Request is not authenticated

Examples

Missing API Key:

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "X-API-Key header is required"
  }
}

Invalid API Key:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

---

Validation Errors

Code	HTTP Status	Description
VALIDATION_ERROR	400	Request body/parameters validation failed
MISSING_FILES	400	No files were uploaded
MISSING_SELFIE	400	Selfie image is required but not provided
MISSING_ID_FRONT	400	ID front image is required but not provided
MISSING_ID	400	Verification ID parameter is required
INVALID_FILE_TYPE	400	Uploaded file type is not supported
FILE_TOO_LARGE	400	Uploaded file exceeds the size limit (10MB)

Examples

Missing Selfie:

{
  "success": false,
  "error": {
    "code": "MISSING_SELFIE",
    "message": "Selfie image is required"
  }
}

Invalid File Type:

{
  "success": false,
  "error": {
    "code": "INVALID_FILE_TYPE",
    "message": "Invalid file type. Allowed types: JPEG, PNG, WebP"
  }
}

Validation Error:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid profile picture URL"
  }
}

---

Verification Errors

Code	HTTP Status	Description
VERIFICATION_ERROR	500	General verification processing error
PROFILE_PICTURE_ERROR	400	Failed to fetch the profile picture URL
FACE_COMPARISON_ERROR	400	Face comparison failed (unclear photos)
SERVICE_UNAVAILABLE	503	Required service (Rekognition/OCR) is unavailable
NOT_FOUND	404	Verification not found

Examples

Profile Picture Fetch Error:

{
  "success": false,
  "error": {
    "code": "PROFILE_PICTURE_ERROR",
    "message": "Failed to fetch profile picture from URL: HTTP 404"
  }
}

Face Comparison Error:

{
  "success": false,
  "error": {
    "code": "FACE_COMPARISON_ERROR",
    "message": "Face comparison failed. Please ensure clear photos of face."
  }
}

Service Unavailable:

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Face comparison service is not available"
  }
}

---

Session Errors

Code	HTTP Status	Description
SESSION_EXPIRED	401	Session token has expired
INVALID_SESSION	401	Session token is invalid or malformed

Examples

Session Expired:

{
  "success": false,
  "error": "Session has expired"
}

---

General Errors

Code	HTTP Status	Description
NOT_FOUND	404	Endpoint or resource not found
INTERNAL_ERROR	500	Unexpected server error
AUTH_ERROR	500	Internal authentication error

Examples

Endpoint Not Found:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Endpoint not found"
  }
}

---

Handling Errors

Node.js Example

async function verifyWithErrorHandling(selfiePath, profileUrl) {
  try {
    const result = await client.selfieMatch(selfiePath, profileUrl);
    return result;
  } catch (error) {
    switch (error.code) {
      case 'MISSING_API_KEY':
      case 'INVALID_API_KEY':
        console.error('Authentication error - check your API key');
        break;
      
      case 'PROFILE_PICTURE_ERROR':
        console.error('Could not fetch profile picture - check the URL');
        break;
      
      case 'FACE_COMPARISON_ERROR':
        console.error('Face comparison failed - photos may be unclear');
        break;
      
      case 'SERVICE_UNAVAILABLE':
        console.error('Service temporarily unavailable - retry later');
        break;
      
      default:
        console.error('Unknown error:', error.message);
    }
    
    throw error;
  }
}

Python Example

from yeboverify import YeboVerifyClient, YeboVerifyError

client = YeboVerifyClient(api_key)

try:
    result = client.selfie_match(selfie_path, profile_url)
except YeboVerifyError as e:
    if e.code == 'MISSING_API_KEY' or e.code == 'INVALID_API_KEY':
        print('Authentication error - check your API key')
    elif e.code == 'PROFILE_PICTURE_ERROR':
        print('Could not fetch profile picture - check the URL')
    elif e.code == 'FACE_COMPARISON_ERROR':
        print('Face comparison failed - photos may be unclear')
    elif e.code == 'SERVICE_UNAVAILABLE':
        print('Service temporarily unavailable - retry later')
    else:
        print(f'Unknown error: {e.message}')
    
    raise

---

Rate Limiting

When you exceed your rate limit, you'll receive:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  }
}

HTTP Status: 429 Too Many Requests

Headers:

• X-RateLimit-Limit: Your rate limit
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Unix timestamp when the limit resets

Handling Rate Limits

async function verifyWithRetry(selfiePath, profileUrl, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.selfieMatch(selfiePath, profileUrl);
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED' && attempt < maxRetries - 1) {
        const waitMs = Math.pow(2, attempt) * 1000; // Exponential backoff
        console.log(`Rate limited. Waiting ${waitMs}ms...`);
        await new Promise(resolve => setTimeout(resolve, waitMs));
        continue;
      }
      throw error;
    }
  }
}