Error Handling and Defensive Programming Questions

import java.util.concurrent.locks.ReentrantLock;
import java.util.concurrent.TimeUnit;

public class TokenBucket {
    private final long capacity;         // max tokens (burst)
    private final double tokensPerNanos; // refill rate in tokens/nanosecond
    private double tokens;
    private long lastRefillNanos;
    private final ReentrantLock lock = new ReentrantLock();

    public TokenBucket(long capacity, double tokensPerSecond) {
        if (capacity <= 0 || tokensPerSecond <= 0) throw new IllegalArgumentException();
        this.capacity = capacity;
        this.tokensPerNanos = tokensPerSecond / 1e9;
        this.tokens = capacity;
        this.lastRefillNanos = System.nanoTime();
    }

    // Try to acquire a single token. Return true if allowed.
    public boolean tryAcquire() {
        lock.lock();
        try {
            refillInternal();
            if (tokens >= 1.0) {
                tokens -= 1.0;
                return true;
            } else {
                return false;
            }
        } finally {
            lock.unlock();
        }
    }

    // External refill hook (optional): forces a refill based on time elapsed.
    public void refill() {
        lock.lock();
        try {
            refillInternal();
        } finally {
            lock.unlock();
        }
    }

    // internal helper - must be called under lock
    private void refillInternal() {
        long now = System.nanoTime();
        long elapsed = now - lastRefillNanos;
        if (elapsed <= 0) return;
        double add = elapsed * tokensPerNanos;
        tokens = Math.min(capacity, tokens + add);
        lastRefillNanos = now;
    }

    // For observability
    public double getTokens() {
        lock.lock();
        try {
            refillInternal();
            return tokens;
        } finally {
            lock.unlock();
        }
    }
}

# Assumptions:
# - Postgres table idempotency_keys(idempotency_key pk, owner_id, status, response_status, response_headers json, response_body bytea, created_at, expires_at)
# - Redis for short locks with SETNX and TTL
# - process_payment() performs the external side-effect (charge) and may raise

def handle_post(request):
    key = request.headers.get("Idempotency-Key")
    if not key:
        return 400, {"error": "Missing Idempotency-Key"}

    lock_key = f"idemp-lock:{key}"
    got_lock = redis.set(lock_key, uuid(), nx=True, ex=10)  # 10s safety TTL
    row = db.select_for_update("SELECT * FROM idempotency_keys WHERE idempotency_key=%s", key)

    if row is None:
        # create a processing record in a transaction to ensure single writer
        with db.transaction():
            try:
                db.execute("INSERT INTO idempotency_keys (idempotency_key, status, created_at, expires_at) VALUES (%s,'processing', now(), now()+interval '24 hours')", key)
            except UniqueViolation:
                # another concurrent inserter won race; read row
                row = db.select("SELECT * FROM idempotency_keys WHERE idempotency_key=%s", key)

    if row and row.status == "success":
        # replay stored response exactly
        return row.response_status, deserialize_headers(row.response_headers), row.response_body

    if row and row.status == "processing":
        if got_lock:
            # we are the processor; continue
            pass
        else:
            # another process is handling it -> avoid duplicate side-effect
            # Option A: wait/poll with short backoff up to a threshold, then return 202
            return 202, {"Retry-After": "3"}, {"message":"Processing"}
    
    # At this point we hold lock (or we are the designated processor)
    try:
        result = process_payment(request.body)  # side-effectful
        # persist response atomically
        with db.transaction():
            db.execute("UPDATE idempotency_keys SET status='success', response_status=%s, response_headers=%s, response_body=%s WHERE idempotency_key=%s",
                       result.http_status, serialize_headers(result.headers), result.body, key)
        return result.http_status, result.headers, result.body
    except Exception as e:
        # record failure to allow clients to retry and avoid infinite processing
        with db.transaction():
            db.execute("UPDATE idempotency_keys SET status='failure', response_status=%s, response_headers=%s, response_body=%s WHERE idempotency_key=%s",
                       500, json.dumps({"error": str(e)}), b"", key)
        raise
    finally:
        if got_lock:
            redis.delete(lock_key)