## Request limits

| Surface | Limit |
| --- | --- |
| Email verification (`/api/v1/email/verify/*`) | 60 requests per minute per key |
| Other metered tools behind the gateway | 10 requests per second per key by default |

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](mailto:hello@1toolring.com).

## 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](https://1toolring.com/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

```http
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.