Errors

Gateway errors use FastAPI's detail envelope. The public API surface is documented in the API Reference.

Session creation errors

HTTP 401 — missing or malformed API key

POST /api/v1/sessions/create requires X-API-Key. A missing header or a value without a recognized key prefix returns:

{
  "detail": "Missing or malformed API key"
}

An unknown, revoked, or otherwise invalid key returns:

{
  "detail": "Invalid API key"
}

HTTP 403 — disabled tenant

{
  "detail": "Tenant disabled"
}

HTTP 402 — insufficient prepaid credit

A live session cannot be created when the tenant has no free check left for the current UTC month and no prepaid credit:

{
  "detail": {
    "code": "insufficient_credit",
    "message": "Tenant has no prepaid credit — top up to resume verifications"
  }
}

Test-key sessions do not use prepaid credit.

HTTP 422 — validation

Invalid request bodies, headers, and path parameters return a sanitized list:

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["body", "target_age"],
      "msg": "validation failed"
    }
  ]
}

The gateway deliberately replaces validation messages with "validation failed" and omits the rejected input. This biometric-safe response never echoes request input.

HTTP 429 — test-session daily cap

When a tenant reaches the test-session daily cap, creation returns:

{
  "detail": "Test session daily cap reached"
}

Session status lookup errors

GET /api/v1/sessions/{session_id}/status requires X-API-Key and has no request body.

HTTP 401 — missing or invalid API key

Missing, invalid, and revoked keys return HTTP 401. The response uses the same "Missing or malformed API key" or "Invalid API key" detail documented for session creation.

HTTP 403 — disabled tenant

A disabled tenant returns HTTP 403.

HTTP 404 — session unavailable

Missing and cross-tenant session IDs return the same HTTP 404 response. This prevents a caller from learning whether a session belongs to another tenant.

{
  "detail": "Session not found"
}

HTTP 409 — missing completion timestamp

A terminal PASSED, FALLBACK, or SPOOF row without completed_at returns HTTP 409. The gateway does not fabricate a status_at timestamp.

{
  "detail": "Session completion timestamp missing"
}

HTTP 422 — malformed session ID

A malformed session UUID returns HTTP 422. The response uses the same sanitized validation shape described above.

Estimated-age lookup errors

By default, the verification response, webhook, and redirect contain only the signed result and its status, and no estimated age. If your tenant enables estimated age visibility, your backend can obtain the estimate through the separate authenticated GET /api/v1/sessions/{session_id}/detected-age operation only for sessions whose shoppers accepted the visibility disclosure. The estimate is stored only for those consented sessions and is deleted when its session record is deleted; session records currently have no fixed automatic deletion period.

The operation uses the same 401 response for a missing or invalid API key and the same 403 response for a disabled tenant. Missing and cross-tenant session IDs both return HTTP 404 with {"detail":"Session not found"}; callers cannot use the route to discover another tenant's session. A malformed UUID returns the sanitized HTTP 422 validation response.

not_consented, pending, not_estimated, and available are successful 200 availability values, not errors. See the verification flow for their meanings.

Return to the Quickstart or review the verification flow.