Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Best practices

Polling strategy

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

  • Phase 1 (fast polling, first ~10 seconds): poll every 1 second. Covers the typical case, where the transaction resolves quickly.

  • Phase 2 (exponential backoff, starting at ~10 seconds if there is still no terminal state): increase the interval progressively (e.g. 2s → 4s → 8s → 15s), with a cap of 15 to 20 seconds between polls. Covers cases that require additional analysis and can take substantially longer.

  • Define a maximum waiting 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: duration can vary substantially between transactions, as 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). For the remaining values of failureReason, consult its table in Check status.

Security

  • Do not store the OAuth2 token on the client. Renew it according to its expiration (see Authentication).

  • Use a operation-id consistent between the asset upload and the start of validation, so that the fileKeys can be resolved.

  • 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: main transaction identifier (returned by POST /v2/daf/validate and in each status query). It is the key data point 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 you provide in the headers: operation-id and consumer-id.

When opening a support ticket, always include the transactionId (and the X-Trace-Id if you have it recorded). Check with Facephi the retention periods applicable to your Integration.

Last updated