All error responses follow a consistent JSON structure. The error.code field contains a machine-readable string identifier that you should use in your error handling logic. Never rely on the message field, which may change.

Error response format

{
  "success": false,
  "error": {
    "code": "FACE_NOT_FOUND",
    "message": "No face found with the given ID in this collection."
  },
  "request_id": "req_01j8...",
  "timestamp": "2024-01-15T11:22:33Z"
}

HTTP status codes

Authentication errors

Face & recognition errors

Collection & API key errors

Validation errors

When multiple fields fail validation, the error includes a details array:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [
      {"field": "name", "message": "name is required"},
      {"field": "collection_id", "message": "collection_id must be a valid UUID"}
    ]
  }
}

Handling rate limits

When a 429 is returned, check the Retry-After header for the number of seconds to wait before retrying:

async function identifyWithRetry(formData, apiKey, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(
      'https://your-domain.com/api/v1/collections/COLLECTION_ID/identify',
      { method: 'POST', headers: { 'X-API-Key': apiKey }, body: formData }
    )
    if (res.status === 429) {
      const wait = parseInt(res.headers.get('Retry-After') ?? '5', 10)
      await new Promise(r => setTimeout(r, wait * 1000))
      continue
    }
    const data = await res.json()
    if (!data.success) throw new Error(data.error.code)
    return data
  }
  throw new Error('Max retries exceeded')
}