Core Concepts

​Idempotency

Idempotency lets you safely retry API requests without creating duplicate side effects — essential for payment and fraud flows where network failures are common.

Inspired by Flutterwave's idempotency model, Scrub uses the Idempotency-Key header.

​How it works

Send a unique key with any POST request to these endpoints:

  • POST /fraud/analyze/
  • POST /fraud/report/
  • POST /credit/report/
  • POST /credit/inquiry/
POST /v1/fraud/analyze/
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: idem_7k2m9x1p3q
Content-Type: application/json

{ ... }
http
Interactive idempotency demo

​Rules

RuleDetail
Key formatAny unique string up to 255 characters (UUIDs recommended)
ScopeKeys are scoped to your API key and endpoint path
TTLKeys are stored for 24 hours
Same key, same bodyReturns the original response with 200 OK
Same key, different bodyReturns 409 Conflict with error code DUPLICATE_IDempotency
Missing keyRequest is processed normally (not idempotent)

​Generating keys

import { randomUUID } from 'crypto';

const idempotencyKey = `idem_${randomUUID()}`;
javascript
import uuid

idempotency_key = f"idem_{uuid.uuid4()}"
python

​When to use idempotency

  • Always for fraud analysis on financial transactions
  • Always for credit report generation (async, expensive)
  • Recommended for fraud report submissions
  • Not needed for read-only GET requests
WebhooksErrors