> 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/rest-api/midapi-v2/daf/buenas-practicas.md).

# Best practices

### Polling strategy

Check the status via phased polling, since the resolution time can vary significantly between transactions:

* **Phase 1 (fast polling, first \~10 seconds)**: poll every 1 second. Covers the usual case, in which the transaction resolves quickly.
* **Phase 2 (exponential backoff, from \~10 seconds if there is still no terminal state)**: progressively increase the interval (e.g. 2s → 4s → 8s → 15s), with a cap of between 15 and 20 seconds between polls. Covers cases that require additional analysis and can take substantially longer.
* Define a maximum wait time on the consumer side (e.g. several minutes). If exceeded, treat the case as indeterminate and retry later or contact support.
* Do not assume a fixed response time: the duration can vary substantially between transactions, since some require additional internal analysis before resolving.

### State handling

* `COMPLETED`: read `diagnostic` and, if it is `DECLINED`, `rejectionReason`/`diagnostics[]` to inform the end user.
* `ERROR` / `FAILED`: treat as an integration or service error. Review the data sent and retry if applicable.
* `FAILED` with `failureReason = Validation could not be completed`: transient processing failure (includes internal analysis timeouts). It is safe to retry by starting a new transaction with the same assets (see [Check status](/docs.facephi-en/rest-api/midapi-v2/daf/consultar-estado.md)). For the rest of the values of `failureReason`, consult its table in [Check status](/docs.facephi-en/rest-api/midapi-v2/daf/consultar-estado.md#failurereason).

### Security

* Do not store the OAuth2 Token on the client. Renew it according to its expiration (see [Authentication](/docs.facephi-en/rest-api/midapi-v2/autenticacion.md)).
* Use a `operation-id` consistent between the asset upload and the start of validation, so that the `fileKeys` are resolvable.
* Treat `transactionId` as an opaque identifier. Do not infer information from its format.

### Traceability for support

To investigate a specific case with support, keep and provide the following identifiers:

* **`transactionId`**: primary transaction identifier (returned by `POST /v2/daf/validate` and in each status query). It is the key data for locating a case.
* **Response header `X-Trace-Id`**: request identifier returned by the API in each response; allows support to correlate the exact call. Recommended to store it together with the `transactionId`.
* **`timestamp`** of the transaction (ISO-8601 format) and the identifiers that you provide in the headers: `operation-id` and `consumer-id`.

When opening an issue, always include the `transactionId` (and the `X-Trace-Id` if you have it recorded). Check with Facephi the retention periods applicable to your integration.