Best practices

operator_id strategy, batch vs single, retries, idempotency, observability.

operator_id strategy

Stable, unique, and opaque. Use a UUID, an employee ID, or a hashed identifier. Never an email or a plaintext name.
One per human. Not one per session. Not one per role.
Regex: alphanumeric plus -_, 1-256 chars.

session_id strategy

Globally unique per interaction. UUID, ULID, or <org>-<operator>-<timestamp>-<seq> all work.
COHESION does not enforce uniqueness server-side in v1.1, but client-side dedup via idempotency keys is supported (see below).

Single vs batch

Use	Endpoint
Real-time middleware	POST /v1/score
End-of-shift import, nightly backfill, historical replay	POST /v1/score/batch

Batch saves request overhead and stays inside per-key rate limits for the same volume.

Idempotency

Both SDKs auto-generate an Idempotency-Key header on every POST. Server-side deduplication is live: retries with the same key return the cached envelope. No manual step needed.

Retries

Only retry on 429 and 5xx. Do not retry 4xx other than 429. The SDKs handle this by default.

Observability

Log request_id from every response alongside your own trace ID.
Set a dashboard alert on 429 rate.
Set a dashboard alert on 5xx rate.
Log the 8-char key prefix for traceability; never the full plaintext key.