> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/technical_documentation/api_reference/models.md).

# Models

## The BinaryData object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"BinaryData":{"type":"string","format":"binary","description":"Encrypted facial capture generated by the Facephi capture component."}}}}
```

## The TimeStamp object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"TimeStamp":{"type":"string","description":"UTC date and time in `%Y-%m-%dT%H:%M:%SZ` format (second precision)."}}}}
```

## The EvaluationResult object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"EvaluationResult":{"type":"object","description":"Public injection attack detection result. The order of the keys is not part of the contract, and clients must ignore unknown fields.","required":["diagnostic","reason","transactionId","timestamp"],"properties":{"diagnostic":{"type":"string","description":"Binary verdict of the evaluation. It is the only field that must decide whether the capture is accepted; any value other than `NoAttack` must be treated as a rejection.\n\n- `NoAttack`: no injection attack was detected; the capture is accepted.\n- `Attack`: an injection attack was detected; the capture is rejected.\n","enum":["NoAttack","Attack"]},"reason":{"type":"string","description":"Reason for the rejection. It is informative and must not be used to decide the outcome. When there are several reasons, only the first one is returned. The service converts the reasons reported by the analysis to PascalCase, so new values may appear; show a generic message for the ones you do not recognize.\n\nPossible values:\n- `None`: the capture was accepted (`NoAttack`).\n- `Unknown`: the capture was rejected without a specific reason reported by the analysis.\n- `UntrustedEnvironment`: the capture was generated in an untrusted runtime environment.\n- `SuspiciousActivity`: the device showed activity patterns associated with an attack.\n- `UntrustedDevice`: the device could not be trusted to be what it claims to be.\n- `SdkIntegrityViolation`: the capture SDK or its libraries appear to have been tampered with.\n- `UntrustedCorruptedPayload`: the payload appears to be corrupted or tampered with.\n- `UntrustedContent`: an injection attack was detected.\n- `UntrustedContentLowConfidence`: signs of an injection attack were detected with lower confidence; the capture must still be treated as rejected.\n","enum":["None","Unknown","UntrustedEnvironment","SuspiciousActivity","UntrustedDevice","SdkIntegrityViolation","UntrustedCorruptedPayload","UntrustedContent","UntrustedContentLowConfidence"]},"transactionId":{"type":"string","format":"uuid","description":"Unique identifier of the evaluation (lowercase UUID v4). A new one is generated on every request, also when the same capture is retried."},"timestamp":{"type":"string","format":"date-time","description":"UTC instant at which the service started handling the request, in ISO-8601 format with milliseconds (`YYYY-MM-DDTHH:mm:ss.SSSZ`)."}}}}}}
```

## The FacephiErrorMessage object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"FacephiErrorMessage":{"type":"string","description":"Documented public error messages returned in HTTP 400 responses.\n\n- Capture that the analysis engine could not evaluate (the three capture endpoints): `NoneBecause*` values.\n- Capture rejected by the experimental replay mitigation (the three capture endpoints): `Replay attack detected`.\n- Unclassified failure of the analysis engine: `ErrorProcessing` (`POST /api/v1/iad/evaluate` and `POST /api/v1/iad/evaluate/custom`) or `ErrorFacialImage` (`POST /api/v1/iad/extract`).\n- License that stopped being valid while the service runs (the three capture endpoints): `Invalid license: <reason> (code: <code>)`. The capture is not analyzed.\n- Request validation on the three capture endpoints: `Empty multipart payload`, `Required multipart field 'capture' not found` and `Empty data in multipart field 'capture'`.\n- Request validation specific to `POST /api/v1/iad/evaluate/custom`: the `pipeline` and `calibration` messages.\n- Service not ready: `Service not initialized` and `Service not configured`.\n\nWhen the analysis engine does not respond, the capture endpoints answer HTTP 503 with `Engine communication error:` followed by the detail (see `ServiceUnavailableResult`). `GET /api/v1/iad/health` answers HTTP 503 when the service cannot handle evaluations.\n","enum":["NoneBecauseFaceTooClose","NoneBecauseFaceNotFound","NoneBecauseFaceTooSmall","NoneBecauseAngleTooLarge","NoneBecauseImageDataError","NoneBecauseLicenseError","NoneBecauseTooManyFaces","NoneBecauseFaceTooCloseToBorder","NoneBecauseFaceCropped","NoneBecauseFaceOccluded","NoneBecauseEyesClosed","Replay attack detected","ErrorProcessing","ErrorFacialImage","Empty multipart payload","Required multipart field 'capture' not found","Empty data in multipart field 'capture'","Required multipart field 'pipeline' not found","Invalid value for 'pipeline'; expected 'iad_r01' or 'iad_r00'","Invalid value for 'calibration'; expected 'regular' or 'hardened'","Service not initialized","Service not configured"]}}}}
```

## The ExtractImageResult object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"ExtractImageResult":{"type":"object","properties":{"image":{"type":"string","format":"byte","description":"Extracted facial image, Base64 encoded (standard RFC 4648 alphabet)."},"mimeType":{"type":"string","description":"MIME type of the extracted image. The service always returns `image/jpeg`."}}}}}}
```

## The MessageResult object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"MessageResult":{"type":"object","properties":{"message":{"type":"string","description":"Response message of the service."}}}}}}
```

## The VersionResult object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"VersionResult":{"type":"object","properties":{"message":{"type":"string","description":"Service version followed by the copyright notice. When the license is not valid, the message appends `. Invalid license: <reason> (code: <code>)`.\n"}}}}}}
```

## The EngineHealthSnapshot object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"EngineHealthSnapshot":{"type":"object","description":"Result of the last analysis engine check made by the service, which `GET /api/v1/iad/health` runs and reuses for up to `engine_health_max_age_seconds`.","properties":{"healthy":{"type":"boolean","description":"Whether the last check succeeded."},"lastHealthKnown":{"type":"boolean","description":"Whether the service has checked the analysis engine since startup. It is `false` until the first check."},"lastHealthCheckAt":{"type":"string","description":"UTC instant of the last check, in `%Y-%m-%dT%H:%M:%SZ` format. Empty until the first check."},"lastError":{"type":"string","description":"Reason of the last failed check, for example `Connection failed`, `Request timeout`, `Engine is unhealthy (503)` or `Engine process ended`. Empty when the last check succeeded. A license that is not valid is not recorded here."}}}}}}
```

## The HealthResult object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"HealthResult":{"type":"object","description":"Healthy service. It is only returned when the license is valid and the last analysis engine check succeeded.","properties":{"message":{"type":"string","description":"Always `Healthy`."},"initialized":{"type":"boolean","description":"Always `true`."},"engine":{"$ref":"#/components/schemas/EngineHealthSnapshot"}}},"EngineHealthSnapshot":{"type":"object","description":"Result of the last analysis engine check made by the service, which `GET /api/v1/iad/health` runs and reuses for up to `engine_health_max_age_seconds`.","properties":{"healthy":{"type":"boolean","description":"Whether the last check succeeded."},"lastHealthKnown":{"type":"boolean","description":"Whether the service has checked the analysis engine since startup. It is `false` until the first check."},"lastHealthCheckAt":{"type":"string","description":"UTC instant of the last check, in `%Y-%m-%dT%H:%M:%SZ` format. Empty until the first check."},"lastError":{"type":"string","description":"Reason of the last failed check, for example `Connection failed`, `Request timeout`, `Engine is unhealthy (503)` or `Engine process ended`. Empty when the last check succeeded. A license that is not valid is not recorded here."}}}}}}
```

## The NumericSummary object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"NumericSummary":{"type":"object","description":"Aggregated summary of a score reported by the analysis, on a 0 to 1 scale.","properties":{"samples":{"type":"integer"},"avg":{"type":"number"},"min":{"type":"number"},"max":{"type":"number"}}}}}}
```

## The QualityMetrics object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"QualityMetrics":{"type":"object","description":"Aggregated quality of the `/evaluate` and `/evaluate/custom` evaluations since the service started. The block is an empty object until the first evaluation or the first capture the analysis engine could not evaluate. `detection` appears with the first successful evaluation, and `summary` appears as soon as the block is not empty.\n\nAn `Attack` verdict is the service detecting an attack, not a low-quality sample, so it never raises `LOW_QUALITY` nor degrades the classification, even when it comes with low scores.\n","properties":{"detection":{"type":"object","properties":{"samples":{"type":"integer","description":"Successful evaluations aggregated."},"noAttack":{"type":"integer","description":"Evaluations with the `NoAttack` verdict."},"attack":{"type":"integer","description":"Evaluations with the `Attack` verdict."},"probability":{"$ref":"#/components/schemas/NumericSummary"},"score":{"$ref":"#/components/schemas/NumericSummary"},"faceProbability":{"$ref":"#/components/schemas/NumericSummary"}}},"summary":{"type":"object","properties":{"lowQualitySamples":{"type":"integer","description":"Captures the analysis engine could not evaluate (`NoneBecause*` errors, such as `NoneBecauseFaceNotFound`). It does not include `Attack` verdicts nor captures rejected with `Replay attack detected`."},"lowQualitySince":{"type":"string","description":"Start of the low-quality episode that keeps the `LOW_QUALITY` alert active. Only present once a capture could not be evaluated."}}}}},"NumericSummary":{"type":"object","description":"Aggregated summary of a score reported by the analysis, on a 0 to 1 scale.","properties":{"samples":{"type":"integer"},"avg":{"type":"number"},"min":{"type":"number"},"max":{"type":"number"}}}}}}
```

## The MetricsAlert object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"MetricsAlert":{"type":"object","properties":{"code":{"type":"string","enum":["LICENSE_EXPIRED","ENGINE_UNAVAILABLE","HIGH_ERROR_RATE","SATURATED","LOW_QUALITY","IDLE"]},"severity":{"type":"string","enum":["critical","warning","info"]},"message":{"type":"string"},"since":{"type":"string","description":"UTC instant associated with the alert. For `LOW_QUALITY`, the start of the low-quality episode; for `ENGINE_UNAVAILABLE`, the last failed analysis engine check; for the other alerts, the time of the snapshot."}}}}}}
```

## The TrafficCounters object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"TrafficCounters":{"type":"object","properties":{"requests":{"type":"integer","description":"Requests handled."},"success":{"type":"integer","description":"Responses with a 2xx status."},"clientErrors":{"type":"integer","description":"Responses with a 4xx status, including HTTP 400 rejections and HTTP 401."},"serverErrors":{"type":"integer","description":"Responses with a 5xx status."},"unauthorized":{"type":"integer","description":"Responses with HTTP 401 (also counted in `clientErrors`)."}}}}}}
```

## The TrafficWindow object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"TrafficWindow":{"type":"object","properties":{"requests":{"type":"integer"},"rps":{"type":"number","description":"Requests per second over the window."},"successRate":{"type":"number","description":"Fraction of 2xx responses."},"errorRate":{"type":"number","description":"Fraction of 4xx and 5xx responses."},"clientErrors":{"type":"integer","description":"Responses with a 4xx status within the window, HTTP 401 included."},"serverErrors":{"type":"integer","description":"Responses with a 5xx status within the window, including the HTTP 503 answers of `GET /api/v1/iad/health` and of the capture endpoints."},"unauthorized":{"type":"integer","description":"Responses with HTTP 401 within the window (also counted in `clientErrors`)."}}}}}}
```

## The EndpointTraffic object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"EndpointTraffic":{"allOf":[{"$ref":"#/components/schemas/TrafficCounters"},{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}}}]},"TrafficCounters":{"type":"object","properties":{"requests":{"type":"integer","description":"Requests handled."},"success":{"type":"integer","description":"Responses with a 2xx status."},"clientErrors":{"type":"integer","description":"Responses with a 4xx status, including HTTP 400 rejections and HTTP 401."},"serverErrors":{"type":"integer","description":"Responses with a 5xx status."},"unauthorized":{"type":"integer","description":"Responses with HTTP 401 (also counted in `clientErrors`)."}}}}}}
```

## The LatencyStats object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"LatencyStats":{"type":"object","description":"Latency in milliseconds.","properties":{"avg":{"type":"integer"},"p50":{"type":"integer"},"p95":{"type":"integer"},"p99":{"type":"integer"},"max":{"type":"integer"}}}}}}
```

## The LatencyWindow object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"LatencyWindow":{"type":"object","properties":{"totalMs":{"$ref":"#/components/schemas/LatencyStats"},"queueMs":{"$ref":"#/components/schemas/LatencyStats"},"sdkMs":{"$ref":"#/components/schemas/LatencyStats"}}},"LatencyStats":{"type":"object","description":"Latency in milliseconds.","properties":{"avg":{"type":"integer"},"p50":{"type":"integer"},"p95":{"type":"integer"},"p99":{"type":"integer"},"max":{"type":"integer"}}}}}}
```

## The OperationalMetricsResponse object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"OperationalMetricsResponse":{"type":"object","description":"Cheap operational snapshot for observability and scraping. It only reads state already observed in memory and does not call the analysis engine.","properties":{"schemaVersion":{"type":"string"},"service":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"pathBase":{"type":"string"},"configuredThreads":{"type":"integer"}}},"state":{"type":"object","properties":{"initialized":{"type":"boolean"},"license":{"type":"object","properties":{"valid":{"type":"boolean"}}},"engine":{"$ref":"#/components/schemas/EngineHealthSnapshot"},"classification":{"type":"string","description":"Summary of the service state according to the `metrics_*` thresholds.","enum":["ok","idle","degraded","saturated","unhealthy","unknown"]}}},"traffic":{"type":"object","description":"Every request handled by the service, management requests included.","properties":{"totals":{"$ref":"#/components/schemas/TrafficCounters"},"windows":{"type":"object","properties":{"1m":{"$ref":"#/components/schemas/TrafficWindow"},"5m":{"$ref":"#/components/schemas/TrafficWindow"},"15m":{"$ref":"#/components/schemas/TrafficWindow"}}},"byEndpoint":{"type":"array","description":"One entry per endpoint that has already received requests.","items":{"$ref":"#/components/schemas/EndpointTraffic"}}}},"saturation":{"type":"object","properties":{"inflight":{"type":"integer"},"maxInflight1m":{"type":"integer"},"configuredThreads":{"type":"integer"},"queueP95Ms1m":{"type":"integer"},"backlogSuspected":{"type":"boolean"}}},"latency":{"type":"object","properties":{"scope":{"type":"string"},"windows":{"type":"object","properties":{"1m":{"$ref":"#/components/schemas/LatencyWindow"},"5m":{"$ref":"#/components/schemas/LatencyWindow"},"15m":{"$ref":"#/components/schemas/LatencyWindow"}}}}},"usage":{"type":"object","description":"Business operations handled since startup. Management endpoints (`/health`, `/version`, `/config` and `/metrics`) are excluded.","properties":{"enabled":{"type":"boolean"},"total":{"type":"integer"},"operations":{"type":"object","description":"Requests per operation, keyed by `\"<METHOD> <path>\"`. Only operations that have already received requests appear.","additionalProperties":{"type":"integer"}}}},"quality":{"$ref":"#/components/schemas/QualityMetrics"},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/MetricsAlert"}}}},"EngineHealthSnapshot":{"type":"object","description":"Result of the last analysis engine check made by the service, which `GET /api/v1/iad/health` runs and reuses for up to `engine_health_max_age_seconds`.","properties":{"healthy":{"type":"boolean","description":"Whether the last check succeeded."},"lastHealthKnown":{"type":"boolean","description":"Whether the service has checked the analysis engine since startup. It is `false` until the first check."},"lastHealthCheckAt":{"type":"string","description":"UTC instant of the last check, in `%Y-%m-%dT%H:%M:%SZ` format. Empty until the first check."},"lastError":{"type":"string","description":"Reason of the last failed check, for example `Connection failed`, `Request timeout`, `Engine is unhealthy (503)` or `Engine process ended`. Empty when the last check succeeded. A license that is not valid is not recorded here."}}},"TrafficCounters":{"type":"object","properties":{"requests":{"type":"integer","description":"Requests handled."},"success":{"type":"integer","description":"Responses with a 2xx status."},"clientErrors":{"type":"integer","description":"Responses with a 4xx status, including HTTP 400 rejections and HTTP 401."},"serverErrors":{"type":"integer","description":"Responses with a 5xx status."},"unauthorized":{"type":"integer","description":"Responses with HTTP 401 (also counted in `clientErrors`)."}}},"TrafficWindow":{"type":"object","properties":{"requests":{"type":"integer"},"rps":{"type":"number","description":"Requests per second over the window."},"successRate":{"type":"number","description":"Fraction of 2xx responses."},"errorRate":{"type":"number","description":"Fraction of 4xx and 5xx responses."},"clientErrors":{"type":"integer","description":"Responses with a 4xx status within the window, HTTP 401 included."},"serverErrors":{"type":"integer","description":"Responses with a 5xx status within the window, including the HTTP 503 answers of `GET /api/v1/iad/health` and of the capture endpoints."},"unauthorized":{"type":"integer","description":"Responses with HTTP 401 within the window (also counted in `clientErrors`)."}}},"EndpointTraffic":{"allOf":[{"$ref":"#/components/schemas/TrafficCounters"},{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}}}]},"LatencyWindow":{"type":"object","properties":{"totalMs":{"$ref":"#/components/schemas/LatencyStats"},"queueMs":{"$ref":"#/components/schemas/LatencyStats"},"sdkMs":{"$ref":"#/components/schemas/LatencyStats"}}},"LatencyStats":{"type":"object","description":"Latency in milliseconds.","properties":{"avg":{"type":"integer"},"p50":{"type":"integer"},"p95":{"type":"integer"},"p99":{"type":"integer"},"max":{"type":"integer"}}},"QualityMetrics":{"type":"object","description":"Aggregated quality of the `/evaluate` and `/evaluate/custom` evaluations since the service started. The block is an empty object until the first evaluation or the first capture the analysis engine could not evaluate. `detection` appears with the first successful evaluation, and `summary` appears as soon as the block is not empty.\n\nAn `Attack` verdict is the service detecting an attack, not a low-quality sample, so it never raises `LOW_QUALITY` nor degrades the classification, even when it comes with low scores.\n","properties":{"detection":{"type":"object","properties":{"samples":{"type":"integer","description":"Successful evaluations aggregated."},"noAttack":{"type":"integer","description":"Evaluations with the `NoAttack` verdict."},"attack":{"type":"integer","description":"Evaluations with the `Attack` verdict."},"probability":{"$ref":"#/components/schemas/NumericSummary"},"score":{"$ref":"#/components/schemas/NumericSummary"},"faceProbability":{"$ref":"#/components/schemas/NumericSummary"}}},"summary":{"type":"object","properties":{"lowQualitySamples":{"type":"integer","description":"Captures the analysis engine could not evaluate (`NoneBecause*` errors, such as `NoneBecauseFaceNotFound`). It does not include `Attack` verdicts nor captures rejected with `Replay attack detected`."},"lowQualitySince":{"type":"string","description":"Start of the low-quality episode that keeps the `LOW_QUALITY` alert active. Only present once a capture could not be evaluated."}}}}},"NumericSummary":{"type":"object","description":"Aggregated summary of a score reported by the analysis, on a 0 to 1 scale.","properties":{"samples":{"type":"integer"},"avg":{"type":"number"},"min":{"type":"number"},"max":{"type":"number"}}},"MetricsAlert":{"type":"object","properties":{"code":{"type":"string","enum":["LICENSE_EXPIRED","ENGINE_UNAVAILABLE","HIGH_ERROR_RATE","SATURATED","LOW_QUALITY","IDLE"]},"severity":{"type":"string","enum":["critical","warning","info"]},"message":{"type":"string"},"since":{"type":"string","description":"UTC instant associated with the alert. For `LOW_QUALITY`, the start of the low-quality episode; for `ENGINE_UNAVAILABLE`, the last failed analysis engine check; for the other alerts, the time of the snapshot."}}}}}}
```

## The ConfigData object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"ConfigData":{"type":"object","description":"Public view of the runtime configuration returned by `GET /api/v1/iad/config`. Every value is returned as a string. It contains the service parameters (`port`, `number_of_threads`, `connection_timeout`, `keep_alive_request_number`, `client_max_body_size`, `logger_path`, `logger_level`, `logger_rotation` and `logger_max_files`) with their default value or the one set in `config.json`, and any other parameter defined in `config.json` or sent to `POST /api/v1/iad/config`. It does not reflect values set through environment variables. JWT authentication settings are intentionally omitted. The response may contain additional keys; ignore the ones you do not recognize.\n","additionalProperties":{"type":"string"},"properties":{"port":{"type":"string"},"number_of_threads":{"type":"string"},"connection_timeout":{"type":"string"},"keep_alive_request_number":{"type":"string"},"client_max_body_size":{"type":"string"},"logger_path":{"type":"string"},"logger_level":{"type":"string"},"logger_rotation":{"type":"string"},"logger_max_files":{"type":"string"},"engine_url":{"type":"string","description":"Base URL of the capture analysis runtime. Only present when it is defined in `config.json`."},"metrics_error_rate_warning":{"type":"string","description":"Example of a `metrics_*` threshold. Only present when it is defined in `config.json` or has been sent to `POST /api/v1/iad/config`."}}}}}}
```

## The ConfigUpdateRequest object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"ConfigUpdateRequest":{"type":"object","required":["config_json_string"],"properties":{"config_json_string":{"type":"string","description":"JSON string with the configuration parameters to change. Only the read-write parameters listed in `POST /api/v1/iad/config` are applied. JWT authentication settings (`auth_*`) are rejected and can only be set at startup."}}}}}}
```

## The BadRequestResult object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"BadRequestResult":{"type":"object","description":"The request is not valid, the capture could not be processed, or the license of the service is not valid.","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string","description":"Service error message or error normalized by Facephi.","oneOf":[{"$ref":"#/components/schemas/FacephiErrorMessage"},{"type":"string"}]},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"FacephiErrorMessage":{"type":"string","description":"Documented public error messages returned in HTTP 400 responses.\n\n- Capture that the analysis engine could not evaluate (the three capture endpoints): `NoneBecause*` values.\n- Capture rejected by the experimental replay mitigation (the three capture endpoints): `Replay attack detected`.\n- Unclassified failure of the analysis engine: `ErrorProcessing` (`POST /api/v1/iad/evaluate` and `POST /api/v1/iad/evaluate/custom`) or `ErrorFacialImage` (`POST /api/v1/iad/extract`).\n- License that stopped being valid while the service runs (the three capture endpoints): `Invalid license: <reason> (code: <code>)`. The capture is not analyzed.\n- Request validation on the three capture endpoints: `Empty multipart payload`, `Required multipart field 'capture' not found` and `Empty data in multipart field 'capture'`.\n- Request validation specific to `POST /api/v1/iad/evaluate/custom`: the `pipeline` and `calibration` messages.\n- Service not ready: `Service not initialized` and `Service not configured`.\n\nWhen the analysis engine does not respond, the capture endpoints answer HTTP 503 with `Engine communication error:` followed by the detail (see `ServiceUnavailableResult`). `GET /api/v1/iad/health` answers HTTP 503 when the service cannot handle evaluations.\n","enum":["NoneBecauseFaceTooClose","NoneBecauseFaceNotFound","NoneBecauseFaceTooSmall","NoneBecauseAngleTooLarge","NoneBecauseImageDataError","NoneBecauseLicenseError","NoneBecauseTooManyFaces","NoneBecauseFaceTooCloseToBorder","NoneBecauseFaceCropped","NoneBecauseFaceOccluded","NoneBecauseEyesClosed","Replay attack detected","ErrorProcessing","ErrorFacialImage","Empty multipart payload","Required multipart field 'capture' not found","Empty data in multipart field 'capture'","Required multipart field 'pipeline' not found","Invalid value for 'pipeline'; expected 'iad_r01' or 'iad_r00'","Invalid value for 'calibration'; expected 'regular' or 'hardened'","Service not initialized","Service not configured"]},"TimeStamp":{"type":"string","description":"UTC date and time in `%Y-%m-%dT%H:%M:%SZ` format (second precision)."}}}}
```

## The ServiceUnavailableResult object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"ServiceUnavailableResult":{"type":"object","description":"The service cannot handle the request right now. The capture endpoints return it when the analysis engine does not respond; `GET /api/v1/iad/health` returns it when the service cannot handle evaluations.","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string","description":"Reason why the service is not available."},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"TimeStamp":{"type":"string","description":"UTC date and time in `%Y-%m-%dT%H:%M:%SZ` format (second precision)."}}}}
```

## The UnauthorizedResult object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"UnauthorizedResult":{"type":"object","description":"The authentication token is missing or invalid.","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string","description":"Reason for the rejection (`Missing authentication token`, `Authentication secret is not configured`, `JWT token is expired`, `JWT token is not yet valid`, `JWT token does not include exp claim` or `JWT token validation failed`). Use the HTTP status code, not the text, to make decisions."},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"TimeStamp":{"type":"string","description":"UTC date and time in `%Y-%m-%dT%H:%M:%SZ` format (second precision)."}}}}
```

## The ExceptionResult object

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"components":{"schemas":{"ExceptionResult":{"type":"object","description":"An unhandled internal error occurred.","properties":{"status":{"type":"number"},"error":{"type":"string"},"exception":{"type":"string","description":"Description of the internal error."},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"TimeStamp":{"type":"string","description":"UTC date and time in `%Y-%m-%dT%H:%M:%SZ` format (second precision)."}}}}
```