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
Client-side generate an idempotency_key per logical submission. Both SDKs support this. Server-side dedup cache lands in v1.2 (see versioning).
Retries
Only retry on 429 and 5xx. Do not retry 4xx other than 429. The SDKs handle this by default.
Observability
- Log
request_idfrom 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.