Reliability and reconciliation

The Evaluate endpoint commits the core decision before starting post-response work. If the caller times out or loses the connection, the transaction may already exist in Vantrace even though the response was not received.

A timeout is an unknown outcome

Do not treat a timeout as proof that evaluation failed. Do not immediately submit the same transaction again.

1. Mark the local attempt as outcome unknown.
2. Retain the original reference_id and caller-generated X-Request-ID.
3. Prevent another worker from submitting the same transaction concurrently.
4. Apply your approved service-degradation policy.
5. Reconcile the original attempt before deciding whether another submission is safe.

No server-side idempotency guarantee

The live Evaluate route does not currently claim or replay requests idempotently. Reusing reference_id does not guarantee that a duplicate request will be rejected or return the original response.

Timeout configuration

Setting	Recommendation
Connect timeout	Configure an explicit value appropriate for your network path and validate it under load.
Read timeout	Configure an explicit value that accommodates the agreed service target and network variance.
Server processing	The documented core-evaluation target is under 350 ms; it excludes network latency and post-response work and is not stated as an SLA.
Retry strategy	Reconcile the original attempt first; never retry solely because the client timed out.

Vantrace does not publish universal connect or read timeout numbers because network topology and institutional continuity policy differ. Confirm production values during onboarding.

Caller-side duplicate protection

Before calling Vantrace, atomically record a local attempt keyed by your stable transaction reference. Only one worker should be allowed to own an attempt at a time.

A practical state model is:

not_submitted -> in_flight -> decided
                        \-> outcome_unknown -> reconciled

request sent
    │
    ▼
 timeout
    │
    ▼
do not assume failure
    │
    ▼
reconcile using reference_id / trx_id / X-Request-ID
    │
    ▼
retry only when your approved policy determines it is safe

Do not create a new reference merely to retry the same financial transaction. That makes reconciliation harder and can create duplicate downstream work.

References to retain

Value	When available	Purpose
Your reference_id	Before submission	Connects the attempt to your transaction record.
X-Request-ID	Before submission	Required fresh UUID that traces the request through gateways and logs.
trx_id	Successful JSON response	Identifies the committed Vantrace transaction.
UTC attempt time	Before submission	Narrows operational searches.
HTTP status	When a response arrives	Distinguishes validation, authentication, and server failures.

Never record the API key, HMAC secret, or raw signature in operational logs.

Continuity policy

Whether an institution allows, delays, or declines a transaction during a dependency failure is an institutional policy decision. The API documentation does not prescribe one universal fail-open or fail-closed policy.

Your implementation must make that policy explicit for:

• Connection timeout before response headers.
• Connection loss while reading the body.
• 500 and 503 responses.
• Invalid or unparseable error bodies.
• An incomplete decision with should_block: true.