Idempotency

Every operation requires idempotency_key. Generate it once for a logical request and reuse it only when retrying that same operation and subject.

const idempotencyKey = crypto.randomUUID()

Clawdbase uses the key to locate a prior ledger receipt. A replay of an already settled successful request returns idempotent: true, its ledger ID and the current balance without invoking or charging the operation again.

The key is bound to the original operation, channel, subject and Access Key. Reusing it with different request identity returns 409 with code: "idempotency_conflict"; Clawdbase does not run or charge either request in that conflict response.

Rules

• Use enough entropy to avoid collisions across clients.
• Persist the key with your job or workflow state.
• Do not reuse it for a different subject or operation.
• Treat a missing result on an idempotent receipt as a confirmation of prior settlement, not a new score payload.

The current API cannot recover an original result that never reached your application. Use the returned ledger ID to confirm settlement with Clawdbase support. Submit a new logical request with a new idempotency key only when a fresh assessment is required; it receives the normal charge.

Key design

An idempotency key identifies the business action, not an individual HTTP attempt. Good keys combine a stable job or event ID with the operation boundary. Avoid timestamps alone because two workers can create different timestamps for the same job.

function operationKey(jobId: string, operation: string, subjectId: string) {
  return `${jobId}:${operation}:${subjectId}`
}

If keys could expose customer or repository information in logs, hash or replace those segments with internal IDs.

Retry sequence

Concurrency

Multiple workers can race on the same job. Clawdbase scopes each idempotency key to the authenticated user and permits one logical reservation. Your own queue should still use job locking so workers do not apply the returned decision twice.

Conflicts

Never reuse a key for another operation or subject. An idempotency_conflict response is a client data-integrity error: replay the original request, or create a new key for a genuinely new logical job. Never silently change the request stored against an existing key.

Retention

Keep idempotency keys at least as long as your retry and reconciliation window. Store the Clawdbase ledger ID beside the key so support can correlate an application job without needing credentials or raw provider data.