Agent Wranglers

PRC-11Recommended

Bound how far a cap can be overshot

Write the largest overshoot each spend cap allows, such as 1% of the cap. Enforce it with holds or a strongly consistent counter on the request path, never with a total that lags.

By Agent Wranglers. Updated .

How to do it

Usage totals often come from a pipeline that lags by minutes. A customer, or a runaway agent, can send thousands of requests before the total reaches the cap. Take a hold for each request in the same store that checks the cap, as Hold credits before costly work and settle after does. Several servers then cannot all pass the check at once. When the cap store is spread over regions, give each region a share of the remaining cap. Requests in flight when the cap is reached may finish, and they are the overshoot you wrote down. Refuse new ones as Let customers cap their spend says.

Examples

JavaScript example

export async function reserveUnderCap(db, accountId, costMinor) {
  const reserved = await db.query(
    `UPDATE spend_caps SET held_minor = held_minor + $2
     WHERE account_id = $1 AND spent_minor + held_minor + $2 <= cap_minor
     RETURNING account_id`, [accountId, costMinor])
  return reserved.rowCount === 1
}

Python example

def reserve_under_cap(db, account_id, cost_minor) -> bool:
    reserved = db.execute(
        """UPDATE spend_caps SET held_minor = held_minor + %s
           WHERE account_id = %s AND spent_minor + held_minor + %s <= cap_minor
           RETURNING account_id""", (cost_minor, account_id, cost_minor))
    return reserved.rowcount == 1

How to check

A load test sends 1,000 parallel requests from one account with a cap worth 100 of them. At most the written overshoot above 100 succeeds, and the rest get the cap error.

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/pricing/spend-caps-and-alerts/cap-overshoot">Agent Wranglers pricing, plans and entitlements playbook</a>. In code you write, add a comment next to it with the same link.