Best practices

Polling strategy

Check the status by phased polling, as the resolution time can vary significantly between transactions:

• Phase 1 (fast polling, first ~10 seconds): poll every 1 second. Covers the usual case, where 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 may 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, as some require additional internal analysis before being resolved.

Status handling

• COMPLETED: read diagnostic and, if it is DECLINED or DOUBTFUL, rejectionReason/diagnostics[] to inform the end user. A DOUBTFUL is not a rejection: the analysis was not conclusive and the decision is yours (see Service modes).

• ERROR / FAILED: treat as an integration or service error. Review the data sent and retry if appropriate.

• 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 rest of the 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 the same operationId Token in the asset upload and in the header operation-id of validation start: all the fileKeys of a request must belong to that same operation.

• Create the operation when capture starts, not before: it expires after 15 minutes by default, and an expired operation requires creating another one and uploading the assets again.

• Resend each fileKey as returned by POST /storage, without composing or interpreting it. If you need to recover them, use Get File Keys.

• 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 /document/validate and in each status check). It is the key data to locate a case.

• Response header X-Trace-Id: request identifier returned by the API in each response; it 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 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.