Request limits

Exceeding a limit answers 429 (RATE_LIMITED on email verification, with Retry-After: 60). Back off and retry. If you need a higher limit, write to us.

Credits

• 1 credit = Rp1. The wallet is a whole number of rupiah; no call produces a fractional charge.
• 1ToolRing is pay as you go. There are no plans, subscriptions or monthly allowances: you top up a prepaid balance and each successful call deducts its listed price. Top-ups are Rp29.000, Rp59.000, Rp109.000 or Rp249.000 and add exactly that many credits. See pricing.
• New accounts currently receive a one-time 3,000-credit signup bonus when the email is verified (limited per network per day). It is never refilled.
• Every catalog entry carries its price: price_credits per price_unit. Email verification is 105 credits per chargeable address. Job, report and list endpoints are free.
• An entry without a verified price is refused with 409 CATALOG_PRICE_UNVERIFIED or 402 UNPRICED_PRODUCT. “We cannot price this” and “this is free” are different statements.

How a charge happens

1. Hold. The price is reserved before the handler runs. A wallet that cannot cover it is refused with 402 INSUFFICIENT_CREDITS before any work.
2. Settle. On a delivered 2xx, exactly one usage row is written for the amount actually charged.
3. Release. On any other outcome (a non-2xx, a timeout, a disconnect) the hold is given back in full. A failed call costs nothing.

Reading the charge

X-ToolRing-Credits: 105
X-ToolRing-Cache: miss

X-ToolRing-Credits is the rupiah amount actually charged for this call, written by the settle that closed it. It is 0 for a failed call, a refusal, a free endpoint, or a cache hit.

The durable record is your activity log in the dashboard. Each row carries cost_charged, status_code, upstream_status, cache_state and error_code; the header and the row cannot disagree.

Caps and policy

A key, org or agent can carry a credit cap, a call cap, and deny rules for hosts, paths or methods. Breaching one answers 402 BUDGET_EXCEEDED, 402 CALL_CAP_EXCEEDED or 402 POLICY_DENIED. Tag a call with X-ToolRing-Tag: customer=<id> to attribute spend to a per-tag budget.

Usage visibility

• GET /user/usage aggregates monthly usage per product for the authenticated user.
• GET /billing/credits returns the balance, the per-product prices and the ledger.
• GET /api/v1/email/verify/credits reports the balance and how many addresses it still covers.